cypher-mcp

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

With no annotations, the description carries full burden. It discloses that the tool is free (no credits consumed) and requires proof of npub ownership via dpop_token. It does not mention rate limits or error behavior, but for a read-only account statement tool, the provided transparency is adequate.

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

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

Two concise paragraphs: first states purpose and contents, second clarifies it's not the Authority balance and mentions free usage and authentication. No fluff, well structured.

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

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

Given an output schema exists, the description need not detail return values. It covers purpose, contents, prerequisites, cost, and differentiation. Complete for a read tool with 3 parameters.

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 parameters are well-documented there. The description adds that dpop_token is for proof of ownership, but days is already described in schema. Minimal added value beyond structured data.

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

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

The description clearly states the tool generates a patron's account statement with specific contents (purchase history, credit tranches, usage breakdown, daily logs). It distinguishes from sibling 'check_authority_balance' by noting it's not the Authority tax balance, and from 'account_statement_infographic' by 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?

The description explains prerequisites (npub and dpop_token) and that it's free. It implicitly tells when to use (to view spending account details) but doesn't explicitly mention when not to use or alternatives like the infographic version. Still clear enough.

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

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

With no annotations, the description discloses cost (1 api_sat per call) and proof verification mechanism (debit_or_deny). This provides key behavioral context beyond basic input/output.

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

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

The description is two sentences: first states purpose, second details output and constraints. No unnecessary words, well-structured and front-loaded.

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

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

The tool has an output schema, so return values are covered. The description explains visual output, cost, and verification. For a moderately complex tool with sibling differentiation, this is complete.

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

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

Schema coverage is 100%. The description adds no new meaning to parameters beyond what the schema already provides (e.g., 'days' is already described). Baseline score is appropriate.

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

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

The description clearly states it generates a visual SVG infographic of account statements, listing specific visual elements. It distinguishes itself from the sibling 'cypher_account_statement' by noting it returns the same data but rendered, implying different use cases.

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 mentions it returns the same data as account_statement but does not explicitly state when to use this tool versus the raw data version. Usage context is implied but not clearly articulated.

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?

The description discloses the polling behavior ('Polls the Authority MCP-to-MCP') and lists possible return statuses (pending/approved/rejected/provisioned). It also states it's free. However, with no annotations provided, the description carries the full burden for behavioral disclosure; it omits details like being read-only (likely), side effects, or permission 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?

The description is concise—two sentences with no wasted words. Key information (free, polling behavior, possible statuses) is front-loaded in the first sentence. Every sentence adds value.

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 tool with two parameters and an output schema, the description covers most of the necessary context (what it does, how it works, statuses). However, it lacks explanation of the 'dpop_token' parameter and does not describe the output format (though an output schema exists). The missing parameter detail reduces 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 input schema has 0% description coverage, so the description must compensate. It implicitly explains the 'authority_npub' parameter (chosen Authority) but does not mention the 'dpop_token' parameter at all. The description adds some meaning for the required parameter but fails to cover the optional parameter.

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

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

The description clearly states the tool's purpose: checking the adoption-request status of the operator at a chosen Authority. It uses a specific verb ('Check') and resource ('adoption-request status'), making it distinct from sibling tools like cypher_get_operator_onboarding_status or cypher_request_adoption.

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

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

The description provides context for when to use the tool: to check the status of an operator's adoption request. It notes that the tool is free and polls the Authority, giving agents a clear indication of its operation. However, it does not explicitly exclude alternative tools or provide when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It only says 'record' but does not disclose side effects, idempotency, permissions, or whether it creates or updates. Lacks details on persistence or scope.

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

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

The description is a single, concise sentence with no redundant words. It is front-loaded and efficiently conveys the core purpose.

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

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

Given 5 parameters (3 required) and no output schema, the description is too minimal. It does not explain the return value, success conditions, or how the record is stored. Lacks completeness for an agent to invoke confidently.

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 60% (moderate), but the tool description adds no parameter context beyond what's in the schema. It does not explain the role of npub, dpop_token, or the relationship between parameters.

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

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

The description clearly states the tool records a symbol's location for future triage grep scoping, using specific verb 'record' and resource 'symbol location'. However, it does not distinguish from siblings like cypher_index_symbol or cypher_bind_capability_to_symbol.

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

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

The description provides no guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or exclusions.

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

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

With no annotations, the description must fully disclose behavioral traits. It only states 'record an enforceable code invariant' without mentioning side effects, permissions, idempotency, or what happens if the invariant already exists. This is insufficient for safe invocation.

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

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

The description is extremely concise with one short sentence. It is front-loaded but suffers from under-specification, which is not true conciseness.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description is too minimal. It does not explain return values, error conditions, or behavior when invariants conflict. More context is needed for reliable use.

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 50% (only name and rule have descriptions). The model-level description adds no additional meaning beyond what is in the schema. It does not explain 'npub' or 'dpop_token', which are undocumented in the schema.

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

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

The description 'Record an enforceable code invariant' clearly states the tool's action (record) and resource (code invariant). It is specific but does not distinguish from sibling tools like 'cypher_assert_rationale' or 'cypher_guard_invariant_symbol'.

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 usage guidance is provided. The description lacks when to use this tool versus alternatives, prerequisites, or exclusions. The sibling list indicates many related tools, but no differentiation.

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?

The description indicates the provenance is unverified, hinting at data integrity but does not disclose whether the tool performs a write operation, requires authentication, or has side effects. Without annotations, this leaves significant behavioral gaps.

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

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

The description is a single sentence of 10 words, conveying the essential purpose without superfluous information. It is optimally concise.

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 7 parameters (5 required) and no output schema, the description does not explain return values, side effects, or data persistence. It lacks completeness for a write operation 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 71%, with 5 of 7 parameters documented. The tool description adds no extra meaning beyond the schema; it merely restates the purpose. Given moderate coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool records a rationale for a fix by a Journeyman, specifying the verb (record), resource (rationale), and provenance qualifier (unverified). This distinguishes it from other recording tools like cypher_record_triage, but does not explicitly differentiate.

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 guidance is provided on when to use this tool versus alternatives such as cypher_note_rejection or cypher_record_triage. There is no mention of prerequisites or context for use.

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

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

No annotations available, so description must carry full burden. It states the action (author) but does not disclose side effects, permissions, idempotency, or error conditions. Minimal behavioral insight.

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

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

The description is a single, concise sentence. It is not verbose but could benefit from additional context without losing conciseness.

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

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

Given 4 parameters, no output schema, and no annotations, the description is too sparse. It lacks explanation of returns, prerequisites, or behavioral context, making it incomplete for effective use.

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 50% (why and name have descriptions). The description adds no extra meaning beyond repeating 'authoritative' for the why parameter. It does not explain npub or dpop_token, leaving gaps.

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

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

The description 'Author the authoritative why for a capability' clearly states the verb (Author) and resource (capability's why), and distinguishes from sibling 'cypher_suggest_capability_why' via the word 'authoritative'. However, it could be more explicit about the action.

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

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

No guidance on when to use this tool vs alternatives like cypher_suggest_capability_why or cypher_upsert_capability. No prerequisites or context provided.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. The term 'Attach' is vague regarding side effects: is it idempotent? Does it overwrite existing bindings? Requires specific permissions? No such details are provided, leaving the agent uninformed about the operation's impact.

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

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

The description is extremely concise at one sentence. While front-loaded, it sacrifices essential details for brevity, making it under-informative. It could be expanded with minimal extra text to improve clarity without becoming verbose.

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

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

Given the tool's complexity (4 parameters, binding operation, no output schema), the description is incomplete. It lacks information on return values, error scenarios, prerequisites (e.g., capability must exist), and idempotency, which are crucial for correct invocation.

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

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

Schema coverage is 50% (2 of 4 parameters described). The description adds no additional parameter meaning beyond the schema. Parameters npub and dpop_token lack descriptions both in schema and tool description, failing to clarify their purpose or defaults.

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

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

The description clearly states the tool's purpose: attaching a capability to a symbol that implements it. The verb 'Attach' and resources 'capability' and 'symbol' are specific. It distinguishes from siblings like cypher_bind_rationale_to_symbol, but lacks explicit differentiation from cypher_upsert_capability.

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 explicit guidance on when to use this tool versus alternatives. The description implies it is for associating a capability with an implementing symbol, but does not mention prerequisites, side conditions, or when to use other related tools like cypher_upsert_capability.

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

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

No annotations are provided, so the description must fully disclose behavior. 'Attach' implies a mutation, but there is no mention of side effects (e.g., overwriting existing bindings), authorization requirements (though parameters npub and dpop_token hint at authentication), or idempotency. The description lacks critical behavioral details for a mutation 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?

The description is a single sentence, making it concise. However, it is too short for the tool's complexity (4 parameters, no annotations) and lacks important context. It is front-loaded but sacrifices completeness for brevity.

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

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

Given the absence of annotations, no output schema, and 50% schema coverage, the description should provide substantial context. It fails to explain prerequisites (e.g., existence of a rationale from assert_rationale), return value, or behavior under different parameter values. The tool is part of a larger system (Journeyman), and the description does not situate it within that context.

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

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

The input schema covers 50% of parameters with descriptions (symbol_fqn and decision_id), but the description adds no additional meaning beyond what the schema provides. The parameters npub and dpop_token have defaults but no description of their purpose. The tool description does not explain why these parameters are needed or how they relate to the binding operation.

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

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

The description uses a specific verb ('Attach') and resource ('rationale to code symbol'), which clearly indicates the tool's action. However, it does not explain what 'Journeyman's rationale' or 'code symbol' mean in the broader context, leaving some ambiguity. It distinguishes itself from the sibling tool 'cypher_assert_rationale' by focusing on binding rather than creation.

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 guidance is provided on when to use this tool versus alternatives like 'cypher_assert_rationale'. There is no mention of prerequisites (e.g., that a rationale must first be asserted) or situations where this tool should be avoided. The description is too brief to offer any usage context.

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

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

No annotations exist, so description carries full burden. It only states 'Show' but doesn't disclose behavioral traits like idempotency, side effects, or authentication needs.

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?

Single sentence, 4 words, no filler. Very concise, though lacks structure for a multi-parameter tool.

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, and minimal description. Does not explain return format, prerequisites, or behavior beyond a vague 'Show'. Incomplete for a 3-parameter 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 low (33%–only 'name' described). Description adds no meaning for 'npub' or 'dpop_token', failing to compensate for undocumented parameters.

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

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

Description uses verb 'Show' and resource 'capability's patent grounding', indicating a retrieval operation. While clear, it lacks specificity and doesn't distinguish from sibling 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?

No guidance on when to use this tool versus alternatives. No prerequisites, context, or exclusions provided.

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

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

With no annotations, the description carries full burden. It discloses the balance is for certifying purchases, is operator-owned (not patron), and is free. It doesn't explicitly state read-only behavior or lack of side effects, but the nature of checking a balance implies safety.

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?

Five sentences, each adding distinct value: purpose, return value, zero-balance consequence, ownership clarification, cost. No redundant or vague statements.

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

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

Given no parameters and existence of output schema, the description covers all necessary context: what it does, what it returns, when to use it, and consequence of zero balance. It feels complete for a simple check 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?

Zero parameters means baseline 4. The description adds value by explaining the return meaning (sats for certification) and context, which goes beyond the empty schema.

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

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

Clearly states the tool checks the operator's tax balance at the Authority, specifying the resource ('tax balance') and action ('check'). It distinguishes from sibling tools like cypher_check_balance by clarifying this is for certifying patron purchases, not a patron balance.

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?

Explicitly describes when to use (to check operator's tax balance) and provides actionable guidance: when balance hits zero, patron top-ups fail and operator must call purchase_credits. This context helps the agent decide when to invoke and what to do next.

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

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

No annotations provided, so description carries burden. Clearly states free (no credits), requires proof of npub ownership to prevent enumeration. Leaves out explicit readOnly hint but implied by 'check'.

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?

Five sentences, front-loaded with main purpose, each sentence adds value. No wasted words.

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?

Covers purpose, prerequisites, cost, correct sibling comparison. Output schema exists so return format not needed. Complete for a check-balance 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 100% already describes parameters; description adds that dpop_token is a kind-27235 Nostr event, providing additional meaningful context beyond schema.

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

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

Clearly states it checks a patron's credit balance at the operator, distinct from authority_check_balance which checks operator's Authority balance. Verb+resource+scope is specific.

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?

Explicitly says 'use authority_check_balance instead' for operator balance, mentions free usage and proof of npub ownership required.

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?

Despite no annotations, the description transparently explains the behavioral context: the tool is free, requires npub proof to prevent front-running, and that it checks payment status. No contradictions with annotations (none provided).

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?

Four sentences, front-loaded with purpose, no redundant information. Every sentence adds value: purpose, usage instruction, cost, and security rationale.

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

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

Given the presence of an output schema, the description does not need to detail return values. It covers prerequisites, security, and timing. Complete for the tool's complexity.

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

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

Adds significant meaning beyond the schema: explains that invoice_id comes from purchase_credits, npub must be the owner, and dpop_token is a signed Nostr event. With 100% schema coverage, this contextualization is valuable.

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

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

The description clearly states the tool's purpose: 'Check the payment status of a Lightning invoice.' It distinguishes itself from sibling tools by specifying it should be used after paying via purchase_credits.

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?

Explicitly states when to use: 'Call after paying the invoice from purchase_credits.' Also notes it is free and requires npub ownership proof, giving clear guidance on prerequisites.

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

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

No annotations provided, so description carries full burden. It discloses that the operation is a preview (read-only) and costs no credits. It mentions what it shows (base cost, constraint effects). This is sufficient for a non-destructive price check, though it could mention error behavior for invalid tool IDs.

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 plus a bolded note. Front-loaded with purpose. Every sentence is informative. No redundant or filler text.

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

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

Given the presence of an output schema, the description need not detail return values. It covers purpose, free nature, and what is shown. For a simple preview tool, this is mostly complete, though a bit more about when to use (e.g., before costly tool calls) would help.

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 50%. Description adds value for 'tool_id' by clarifying it accepts both UUID and capability strings. Other parameters (npub, dpop_token) are not described beyond schema defaults. Overall, the description partially compensates for missing schema descriptions but not fully.

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?

Description clearly states 'Preview the effective cost of a tool call.' It uses a specific verb (preview) and resource (cost), and distinguishes from dozens of sibling tools that handle accounts, coupons, queries, etc. No ambiguity.

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

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

Description implies usage context: to check cost before calling a tool, and explicitly notes 'Free — no credits required.' However, it does not explicitly state when to avoid this tool or name alternative price-checking methods, so slightly below top score.

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

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

With no annotations provided, the description fully carries the burden. It explicitly states the tool is free, has no side effects, does not evict the cache, and does not touch relays. This clearly communicates the behavioral impact beyond the operation itself.

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

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

The description is three short sentences, front-loaded with the main purpose. Every sentence adds value: purpose, use case, and behavioral traits. No unnecessary words or repetition.

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

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

Given the tool's simplicity, the description is complete. It covers what it does, when to use it, its effects (none), and cost (free). With an output schema present, the description does not need to explain return values. All necessary information is provided.

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

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

The schema provides 100% coverage with detailed parameter descriptions (including that they are required). The tool description adds little beyond what the schema already states, such as where the token comes from, but this is marginal. Baseline 3 is appropriate given schema 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?

The description clearly states the tool checks if a cached dpop_token is valid. It also distinguishes itself from the sibling tool check_oauth_status by specifying it's for the npub-proof flow. The verb 'Check' and resource 'dpop_token validity' 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.

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

The description provides a clear use case: asking whether a paid call will accept the token before burning credits. It mentions it mirrors check_oauth_status, offering some comparison. However, it doesn't explicitly state when not to use this tool or what alternatives exist beyond that one mention.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It does not mention side effects, permissions, rate limits, or whether the operation is read-only or idempotent. As a lookup tool, destructive nature is unlikely but not confirmed.

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?

Single sentence efficiently conveys the tool's core purpose. No redundant or irrelevant 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?

Given the tool's apparent simplicity (one required parameter, no output schema), the description is adequate but leaves unexplained jargon ('code-orienteering scope') and does not clarify the return format or scope semantics. Acceptable for a straightforward lookup but not fully complete.

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

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

Only the 'keyword' parameter has a description in the schema; the other two (npub, dpop_token) have defaults but no semantic context. The tool description only reinforces 'keyword' and adds no meaning to the optional parameters. Schema coverage is low (33%), and the description does not compensate.

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 'Return the code-orienteering scope for an intent keyword' indicates the tool returns a scope related to a keyword, but 'code-orienteering scope' is jargon that may confuse agents. No differentiation from sibling tools like cypher_record_scope or cypher_guard_invariant_symbol.

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 guidance on when to use this tool vs alternatives. The description does not specify prerequisites, limitations, or contextual conditions. With many sibling tools, this omission leaves the agent without strategic direction.

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

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

No annotations present, so description carries full burden. It explains operator restriction and parameter binding syntax but does not disclose behavior on duplicate keys, side effects, rate limits, or authentication details. 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.

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

Three sentences: purpose, binding rule, param_schema format. No filler, every sentence essential. Front-loaded with key info.

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?

Output schema exists, so return values need not be described. Tool has 9 params but high schema coverage; description covers binding and param_schema. Missing details about default values and auth tokens, but schema provides those. Sufficient for a creation 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 89% (high), so baseline is 3. Description adds value by explaining how parameters are referenced as $name in the template and detailing param_schema format (type, required, allowed types). This goes beyond schema descriptions.

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?

Description clearly states 'publish a new named Cypher query template', which is specific and distinct from sibling tools (e.g., execute, get, update). The verb 'publish' and resource 'named Cypher query template' are precise.

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?

Explicit 'Operator-only' indicates restricted usage. While alternatives are not named, the purpose and name imply usage for creation, distinguishing it from execution, retrieval, or update tools. Sibling context reinforces this, but no explicit 'when not to use' is given.

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

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

With no annotations, the description fully discloses cascading deletions, the no-op behavior for chain steps referencing the deleted coupon, and the restriction to operators requiring proof. This provides sufficient behavioral context for safe invocation.

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 sentences, front-loaded with the core action, followed by cascading effects and access restriction. No redundant information; every sentence adds value.

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

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

The description covers the cascading effect, side effects on chain steps, and access control. However, it lacks details on the return format (though output schema exists) and does not mention permanence or error handling. Adequate for a destructive tool with an output schema.

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

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

Schema description coverage is 0%, and the description does not explain either parameter (coupon_id or dpop_token). While coupon_id is self-explanatory and dpop_token is implied by 'requires proof', no formal documentation or format guidance is provided, leaving a significant 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?

The description clearly states 'Delete a coupon' and distinguishes from sibling tools like mint, update, list, forget, and redeem. It also specifies the cascading effect on redemptions, making the scope 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?

The description implies destructive usage via cascade and side effects but does not explicitly contrast with alternative tools like cypher_forget_coupon. The restriction to operator is stated but no guidance on when to choose delete over other operations.

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

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

With no annotations provided, the description responsibly discloses that this is a write operation to a sensitive vault, that it is free, and that proof is required. It does not hide the mutating nature. Could mention permanence or idempotency, but still informative.

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

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

The description is extremely concise: one sentence summary plus two additional sentences with key details. No filler words, front-loaded, and every sentence adds value.

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

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

Given that an output schema exists (so return values need not be explained), the description covers the essential aspects: action, scope, prerequisite, cost, and sensitivity. Missing error handling or idempotency details, but adequate for the tool's complexity.

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

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

The input schema has 100% coverage with clear descriptions for all three parameters. The description adds context about the dpop_token being a proof of ownership, but overall adds limited value beyond schema. Baseline score of 3 appropriate.

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

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

The description clearly states the verb ('remove') and resource ('patron credential field'), and explains it deletes one field without affecting others. It distinguishes from similar tools (update, forget) implicitly but not explicitly, so it's clear but not top-tier.

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 mentions a prerequisite ('Proof of npub ownership is required') and the sensitive nature of the write, but does not explicitly say when to use this tool over siblings like update_patron_credential or forget_credentials. Some guidance is present but insufficient.

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?

Since no annotations are provided, the description must convey behavioral traits. It indicates the tool deletes an entry (destructive action) and restricts usage to operators. However, it does not explain consequences like irreversibility, cascading effects, or required permissions beyond operator status. The term 'delete' is clear but incomplete.

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

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

The description is a single, front-loaded sentence with zero waste. It communicates purpose and a key constraint efficiently.

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?

Despite having an output schema, the description lacks essential context for a deletion tool: parameter semantics, error conditions, and behavioral details beyond operator restriction. For 3 parameters with low schema coverage, it is insufficiently complete.

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

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

Schema description coverage is only 33% (only npub has a description). The description adds no meaning beyond the schema: 'by key' references the key parameter but no details on format, constraints, or how to use npub and dpop_token. With low coverage, the description fails to compensate, leaving agents underinformed.

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

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

The description clearly specifies the action ('delete') and the resource ('a catalog entry'), with a unique identifier ('by key'). It also includes a usage constraint ('Operator-only'). This distinguishes it from sibling tools like cypher_delete_coupon and cypher_delete_patron_credential, which operate on different entities.

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

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

The description explicitly states that the tool is 'Operator-only', providing a clear context for who should use it. However, it does not mention when not to use it or suggest alternative tools for non-operators, though the sibling list implies those exist. The condition is clear but lacks exclusions.

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

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

No annotations are provided, so the description must carry the full burden. It discloses that the operator owns the query text and the agent never sees raw Cypher. It also explains billing behavior: charged only for delivered answers, no charge on failure. However, it does not explicitly state whether executing a query is read-only or may have side effects, leaving some ambiguity.

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

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

The description is a single paragraph that front-loads the core purpose. It includes a billing note without unnecessary fluff. Minor improvement could be structuring the billing note separately, but overall it is appropriately sized and focused.

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

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

Given the complexity of 4 parameters and the existence of an output schema (which need not be described), the description covers purpose, usage, alternative, billing, and parameter binding. It does not mention error handling beyond billing rollback, but overall it is sufficiently complete for an execution 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 high (75%), so baseline is 3. The description adds value by clarifying that 'npub' is required for credit billing and that 'params' are bound as Cypher $params and must match the query's schema. This adds meaning beyond the schema's descriptions, especially for 'npub' and 'params'.

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

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

The description clearly states the action: 'Execute a published, parameterized Cypher query by its key.' It specifies the verb (execute), the resource (published Cypher query), and the means of identification (by key). It also distinguishes from sibling tools by noting that if a query is published as a named tool, you can call that directly instead.

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

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

The description explicitly states when to use this tool: when you have a key to a published query. It also provides an alternative: if the query is published as a named tool, use that directly. Additionally, it includes a billing note explaining charging policy and rollback on failure, which helps the agent decide when it's safe to invoke.

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

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

With no annotations provided, the description carries full burden of behavioral disclosure. It only states the basic function, omitting details like read-only nature, authentication requirements, side effects, or return format. The agent cannot infer safety or constraints.

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

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

Single sentence with no filler words. However, extreme conciseness sacrifices necessary detail; it is efficient but under-specified for a tool with 3 parameters and no annotations.

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

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

Given the lack of output schema, annotations, and parameter descriptions, the description is insufficient. It fails to explain return values, error conditions, or how parameters affect behavior, leaving substantial gaps.

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 'name' described. The tool description adds no parameter information beyond the schema. The purpose of 'npub' and 'dpop_token' remains unclear, and no default behavior or usage context is provided.

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?

Description clearly states verb 'Explain' and resource 'capability', specifying two aspects: why it exists and where it lives. However, it does not explicitly differentiate from sibling tools like cypher_authorize_capability_why or cypher_which_service_handles, which may have overlapping purposes.

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 guidance on when to use this tool versus alternatives. The description does not specify prerequisites, context, or situations where this tool is recommended over siblings with similar names.

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

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

No annotations provided, so description carries full burden. It lacks disclosure of read-only nature, authentication needs, or output format. Only states 'show' without behavioral context.

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 sentence is concise but sacrifices crucial information. It is front-loaded, but too minimal to be useful.

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

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

Given 3 parameters, no output schema, and no annotations, description is severely incomplete. Does not cover return values, prerequisites, or parameter explanations.

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% (only ref described). Description adds no meaning to parameters; roles of npub and dpop_token are unexplained.

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?

Description clearly states the tool shows what a patent reference numeral describes, with specific verb and resource. However, it does not differentiate from siblings like cypher_explain_capability.

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 guidance on when to use this tool versus alternatives like cypher_upsert_patent_element or cypher_capability_patents. The description does not provide context about appropriate use cases.

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

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

No annotations provided, and the description only hints at testing via 'smoke test', but does not disclose side effects, permissions, or return 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?

Single sentence with no redundancy. The parenthetical could be separated, but overall efficient.

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 4 parameters, no output schema, no annotations, and minimal description, the tool is under-specified. The 'smoke test' note hints at limited functionality but does not provide sufficient contextual 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 description links 'between two cities' to the required from_city/to_city parameters, but offers no explanation for the optional npub and dpop_token parameters, leaving them ambiguous.

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

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

The description clearly states 'Find airline routes between two cities', which specifies the verb and resource. The parenthetical '(named-tool smoke test)' slightly detracts but does not obscure the purpose.

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 guidance on when to use this tool versus siblings. No context about prerequisites or exclusions.

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?

Discloses key behaviors: 'Cosmetic only', 'coupon still exists', 'patron can re-redeem', and 'requires proof of npub'. Since no annotations are provided, the description carries full burden and handles it well.

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: first states purpose, second adds behavioral details. No redundant or extraneous information. Efficient and well-structured.

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?

Covers purpose, behavior, and prerequisite. With an output schema (not shown), return value details are likely covered. Lacks mention of error conditions but overall sufficient for a simple removal 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?

With 0% schema description coverage, the description should compensate. It only mentions npub as 'proof' but gives no details on npub, coupon_id, or dpop_token formats or usage.

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

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

Clearly states the verb 'Remove' and resource 'coupon from this patron's redemption list'. Distinguishes from sibling tools like 'cypher_redeem_coupon' (add) and 'cypher_delete_coupon' (permanent deletion).

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?

Explicitly explains that the operation is cosmetic and reversible, and that it requires proof of npub. Provides context on when to use this tool vs others (e.g., not for permanent deletion).

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

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

No annotations provided, so the description carries the full burden. It discloses destruction severity and proof-of-ownership requirement, but lacks details on side effects, error states, or return values. The output schema exists but is not referenced.

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 with no wasted words. Front-loaded with the main action, followed by specific usage instructions. Highly efficient.

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

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

Given the output schema exists, the description adequately covers the tool's destructive nature and auth requirement. It could add idempotency info, but the current content is sufficient for a deletion 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 100%, providing baseline 3. The description adds context for the 'npub' parameter by specifying operator vs patron usage, which goes beyond the schema's description.

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

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

The description clearly states the action (delete vaulted credentials) and the target (specific service and npub). It distinguishes between operator and patron credentials, but does not explicitly differentiate from sibling tools like cypher_delete_patron_credential.

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

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

The description provides guidance on which npub to use (operator vs patron) but does not give when-not-to-use instructions or mention alternative tools for similar operations.

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

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

With no annotations, the description fully discloses behavior: it returns the latest metadata fields listed and handles the case of an empty profile. It identifies the tool as a read operation with no side effects, which is transparent and complete.

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

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

The description is extremely concise (two short sentences) and front-loaded with the core purpose in the first sentence. Every word adds value, no redundancy.

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

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

Given the low complexity (1 parameter, no nested objects) and the presence of an output schema (inferred from context), the description provides all necessary information: purpose, parameter meaning, return fields, and edge case (empty profile). It is complete.

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

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

The schema has 0% coverage, so the description adds critical meaning by identifying 'npub' as the public key identifier. It does not provide format constraints but clearly links the parameter to the tool's purpose, compensating for the schema 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?

The description clearly states the tool reads a public Nostr profile using a specific verb ('Read') and resource ('npub's public Nostr profile'), and specifies the protocol field (NIP-01 kind-0 metadata). Although it does not explicitly differentiate from sibling tools like cypher_publish_nostr_profile, the purpose is unambiguous and specific.

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

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

The description provides context ('Free, no proof — the data is already public on relays') but does not explicitly state when to use this tool versus alternatives or when not to use it. Usage is implied but not guided with exclusions or comparisons.

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

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

No annotations are provided, so the description carries the full burden. It states the tool generates a proof, implying a non-destructive, read-only operation, but does not disclose potential compute cost, authorization needs, or side effects. The description is adequate but not rich in behavioral context.

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

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

The description is a single, front-loaded sentence of 15 words with no filler or redundancy. Every word is informative, making it highly efficient for an agent to parse.

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

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

Given that an output schema exists (so return format is documented) and parameters are fully described, the description provides the core purpose. However, it lacks context on how the proof is structured, verification steps, or when this tool is preferred over similar siblings (e.g., cypher_check_proof_status). The description is minimally complete but could be enhanced.

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% and both parameters have clear descriptions in the schema (npub as Nostr public key, notarization_id as record ID). The tool description does not add any additional semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly specifies the action ('Generate') and the precise object ('Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot'). This distinguishes it from sibling tools like cypher_list_notarizations (listing) or cypher_check_proof_status (checking status), making the purpose 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?

The description implies the tool is used when a Merkle proof is needed for a patron's balance, but does not explicitly state when to use it versus alternatives (e.g., cypher_check_proof_status or cypher_list_notarizations). No prerequisites, exclusions, or conditional guidance are provided, leaving interpretation to the agent.

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?

Describes what it shows (configured/missing/delivery), but no annotations are present. Does not disclose side effects, permissions, or read-only nature explicitly, though 'Report' implies read-only. Could be more transparent.

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 sentences, front-loaded with purpose, no unnecessary words except perhaps 'Free.' which is harmless. Very concise.

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?

Has output schema to explain return values. Description fully covers what the tool does for a simple report tool, no missing context.

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?

No parameters exist, and schema coverage is 100%, so description does not need to add parameter details. Baseline of 4 is appropriate.

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

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

Clearly states 'Report this operator's configuration readiness' with specific verb and resource. Explicitly distinguishes from sibling tool 'get_patron_onboarding_status'.

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?

Provides clear alternative when to use a different tool ('For patron-level credential status, use get_patron_onboarding_status instead'). Lacks broader guidance on when not to use this tool, but the single alternative is valuable.

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

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

With no annotations, the description carries the full burden. It discloses that values are never exposed, the tool is free, requires proof of ownership (dpop_token), and the list itself is sensitive. These are important behavioral traits. It does not mention idempotency or rate limits, but for a read-only list tool, the disclosure is sufficient.

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

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

The description is concise at six sentences, front-loading the purpose in the first sentence. Every sentence adds information (purpose, limitation, usage, cost, auth, sensitivity). It is well-structured and not verbose, though one could argue slight redundancy between the first two sentences.

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

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

Given the output schema exists, the description does not need to detail return values. It covers the operation, auth, cost, and security implications. For a simple list tool with two parameters, the description is complete. It does not discuss pagination or error conditions, but these are not critical for a list of field names.

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 the baseline is 3. The description adds value by explaining why the parameters are needed: 'Proof of npub ownership is required' for dpop_token and 'sensitive' context for npub. This semantic context goes beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool lists patron credential field names, not values, and distinguishes it by emphasizing it is for verification. It provides a specific verb ('List') and resource ('stored patron credential field names'), and the note 'not values' differentiates it from tools that return values. This is explicit and distinct from siblings.

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

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

The description gives context for when to use the tool: 'use this to verify which fields are configured.' It also mentions the security requirement (proof of npub ownership) and sensitivity. However, it does not explicitly state when not to use it or name alternative tools like cypher_update_patron_credential for modification. Still, the guidance is clear enough for an agent.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is free, requires a dpop_token for auth, and distinguishes between service types. It does not hide any destructive behavior and is generally transparent, though it omits rate limits or output specifics (but output schema exists).

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

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

The description is concise and well-structured: a clear purpose statement, followed by service-specific details, and a note on free usage and auth requirement. Every sentence adds value with no fluff.

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

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

Given the presence of an output schema, the description adequately covers the tool's behavior and nuances. It explains credential readiness for two service types and mandates auth, making it complete for an AI agent to understand usage.

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 baseline is 3. The description adds minimal value beyond the schema: it specifies that dpop_token is a kind-27235 event 'for this tool,' but the schema already describes both parameters adequately.

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

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

The description clearly states the tool reports a patron's credential readiness for the operator, with specific details for set-once and dynamic/OAuth2 services. It differentiates from sibling tools by focusing on patron credentials rather than broader onboarding status, but does not explicitly name alternatives.

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

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

The description mentions that proof of npub ownership is required and explains the behavior for different service types, implying when to use it. However, it does not explicitly state when not to use it or suggest alternative tools for other scenarios.

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?

Discloses side effect: self-initializes a scaffold if no model exists. Also states 'No economic data from code.' Adds behavioral context beyond a simple getter.

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 key purpose. No wasted words.

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?

Adequately covers the tool's behavior for a zero-parameter getter, including the initialization scenario. Output schema exists but is not needed for description 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?

No parameters exist, and schema coverage is 100%. Description adds no param info, but baseline for zero parameters is 4.

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

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

Clearly states 'Get the active pricing model for this operator.' with a specific verb and resource, and distinguishes from siblings like set/reset models.

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 guidance on when to use this tool vs. alternatives (e.g., set/reset). Only mentions 'Free.' which is not usage guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the edit_url behavior, when it may be omitted (if credentials not delivered), and assures the raw template is always present. This gives good insight into the tool's response nuances.

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

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

The description is front-loaded with the core purpose and includes valuable detail about edit_url. While slightly verbose, it avoids unnecessary fluff. Every sentence contributes to understanding the tool's behavior.

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

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

Given the existence of an output schema, the description need not detail return values. It sufficiently covers the key behavioral nuance (edit_url) and conditions. However, it could be more complete by clarifying the relationship between input parameters and the fetched catalog entry.

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

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

The input schema covers 3 parameters but only one ('npub') has a description, which is partially incorrect (states 'Required' but it's not in the required list). The description does not add meaning for 'key' or 'dpop_token', failing to compensate for the low schema 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?

The description clearly states 'fetch one catalog entry (template + schema + metadata)' and identifies it as 'Operator-only', distinguishing it from sibling tools like cypher_execute_query_by_key or cypher_list_queries.

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 specifies operator-only access but provides no explicit guidance on when to use this tool versus alternatives such as cypher_create_query, cypher_update_query, or cypher_list_queries. The context about edit_url is useful but insufficient for decision-making.

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

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

No annotations and description lacks any behavioral disclosure: side effects, permissions, or return values not mentioned.

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?

Extremely brief but underspecified. A single confusing sentence does not earn its place; clarity sacrificed for brevity.

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?

Description fails to provide enough context given the tool's complexity (4 params, no output schema, many siblings). Agent cannot determine correct usage.

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 covers 50% of parameters with descriptions. The tool description adds no additional meaning beyond what is in the schema.

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

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

Description 'Register a symbol an invariant guards' is grammatically awkward and vague. It does not clearly state the action or differentiate from siblings like cypher_assert_invariant.

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 guidance on when to use this tool versus alternatives. No context about prerequisites or conditions.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It states 'Index' (a write operation) but does not explain whether previous indexes are overwritten, what happens on conflict, required permissions, or side effects. The description is insufficient for safe invocation.

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

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

The description is a single sentence with no wasted words, appropriate for a simple tool. However, it is under-specified; conciseness should not come at the cost of completeness. A slightly longer description with key details would be more valuable.

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

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

Given the tool has no output schema and moderate parameter count (5), the description is too sparse. It does not explain return values, idempotency, or behavior on duplicate symbols. The context from siblings suggests a complex ecosystem, yet this description provides no integration guidance.

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

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

Schema coverage is 60% (3 of 5 parameters have descriptions). The description adds no additional meaning beyond the schema. It does not explain the purpose of the npub and dpop_token parameters (both with defaults), nor does it clarify the format or constraints for symbol_fqn beyond what the schema provides.

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

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

The description 'Index a code symbol as belonging to a service' clearly states the verb (Index) and resource (code symbol) with a specific intent (belonging to a service). However, it does not differentiate from sibling tools like cypher_symbols_in_service or cypher_which_service_handles, which may have overlapping purposes.

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 guidance is provided on when to use this tool versus alternatives. The description lacks context about typical use cases, prerequisites, or exclusion criteria, leaving the agent to guess based solely on the 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It does not state whether this operation is idempotent, what happens if the linkage already exists, what permissions are required, or any side effects. The description is too brief to convey 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.

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

The description is a single sentence with no unnecessary words. It is extremely concise and easy to process.

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

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

Given the tool's simplicity (recording a link), the description covers the basic purpose. However, it lacks information about return values (no output schema), error conditions, or required prerequisites. For a write operation, more completeness would be helpful.

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 50% (only name and consumer_repo have descriptions). The description adds no further meaning to the parameters, especially npub and dpop_token which lack schema descriptions. The tool description does not compensate for the missing parameter details.

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 'Record that a service consumes a capability' uses a clear verb 'record' and specifies the exact relationship between a service and a capability. It is distinct from sibling tools like cypher_upsert_capability or cypher_bind_capability_to_symbol, which deal with different aspects of capabilities.

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 guidance is provided on when to use this tool versus alternatives such as cypher_upsert_capability, cypher_bind_capability_to_symbol, or cypher_which_service_handles. The description does not mention prerequisites or contexts where this tool is appropriate.

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

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

No annotations are provided, and the description lacks disclosure of behavioral traits such as idempotency, mutability, authentication requirements (despite 'npub' and 'dpop_token' parameters hinting at auth), or error conditions. The description does not clarify whether the operation is a create, update, or overwrite.

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

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

The description is a single sentence, which is concise but lacks structure. It provides no headings, examples, or breaks, and essential information is omitted. The trade-off between brevity and clarity leans too far towards brevity.

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

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

Given the absence of an output schema and the moderate complexity (4 params, linking operation), the description is incomplete. It does not explain return values, success criteria, error conditions, or the effect on the system. Significant gaps remain for the agent to infer.

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

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

Schema description coverage is 50%: only 'name' and 'patent_ref' have descriptions. The tool description adds no additional meaning beyond the schema; it does not explain the role of 'npub' or 'dpop_token'. With missing parameter context, the description 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?

The description 'Ground a capability in a patent reference numeral' clearly states the verb ('Ground') and the resource ('capability' and 'patent reference numeral'). The tool name and description together distinguish it from siblings like 'bind_capability_to_symbol' and 'link_invariant_to_patent', indicating a specific linking action to a patent reference.

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 guidance is provided on when to use this tool versus alternatives such as 'cypher_bind_capability_to_symbol' or 'cypher_link_invariant_to_patent'. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision support.

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

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

No annotations exist, so the description must bear the full burden. It only states the basic action without disclosing side effects (e.g., whether it creates, updates, or deletes data), required permissions, or the result of linkage. The verb 'Ground' is ambiguous in terms of operational impact.

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

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

The description is a single sentence with no redundant words. However, it is perhaps too minimal; given the complexity of the tool, a slightly longer description with parameter context would improve usability without sacrificing conciseness.

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

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

The description is insufficient for the tool's complexity (4 parameters, no output schema). It does not explain what 'ground' means operationally or what the expected output is (e.g., success/failure indicators, data structure). An agent would lack necessary context to invoke it correctly.

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

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

The input schema has 4 parameters with 50% description coverage. The description does not add any meaning beyond the schema—it restates the tool's purpose without explaining the roles of 'name', 'npub', 'dpop_token', or 'patent_ref'. For a tool with medium schema coverage, the description should compensate but fails to.

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

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

The description uses a specific verb 'Ground' and clearly identifies the two resources: invariant and patent reference numeral. It effectively distinguishes from sibling tools like 'cypher_link_capability_to_patent' which targets capabilities, not invariants.

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 guidance is provided on when to use this tool versus alternatives like 'cypher_link_capability_to_patent' or 'cypher_bind_capability_to_symbol'. The description lacks context for appropriate usage, such as prerequisites or contrasting scenarios.

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

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

No annotations are present, so the description must carry the full burden. It implies a mutation (linking) but does not disclose permissions, side effects, or what the linking entails (e.g., whether the issue is updated or a separate record is created).

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

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

The description is a single, concise sentence. It is front-loaded with the action. However, it sacrifices detail for brevity, which reduces informativeness.

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

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

Given 5 parameters and no output schema or annotations, the description should provide more context about how to use the tool, what the linking operation does, and any prerequisites. It is insufficiently complete.

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

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

The schema describes 3 of 5 parameters (repo_name, symbol_fqn, issue_number) – 60% coverage. The description adds no extra meaning beyond the schema. Parameters npub and dpop_token lack descriptions, and the description does not explain their purpose.

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

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

The description clearly states the tool's action: linking an issue to a code symbol that caused it. The verb 'Point' and nouns 'issue' and 'code symbol' are specific, and the tool is distinct from siblings like cypher_assert_rationale or cypher_bind_rationale_to_symbol.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparison to similar tools like cypher_assert_rationale.

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?

Given no annotations, the description fully discloses behavior: it's 'Free, no side effects.' It also explains the key behavioral trait: if a function is renamed or slug rebranded, 'mcp_name in this output changes but tool_id stays,' which is critical for understanding the tool's stable identity contract.

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?

Description is concise (5 sentences) and front-loaded with the action. Every sentence adds value: purpose, usage context, behavioral nuance, and guarantees. No wasted words.

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 an output schema present (indicated by context), the description need not detail return values. It covers the purpose, usage, behavioral stability, and safety, making it complete for a read-only, no-parameter 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?

Tool has zero parameters and schema coverage is 100% (trivially). Baseline for 0 parameters 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.

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

Description clearly states action: 'Return canonical (tool_id, mcp_name, …) for every registered tool.' It uniquely identifies the tool as a list of canonical identities, distinguishing it from sibling tools by explaining its role as the authoritative source for tool identification.

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?

Provides explicit when-to-use guidance: 'The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools.' Also specifies a concrete use case: 'Reconcile uses this output to UUID-join against the stored pricing model — no name-based UUID derivation, no guessing.' This goes beyond typical usage hints.

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

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

No annotations exist, and the description does not disclose side effects, authorization requirements, or result details. It only states the action without behavioral nuance.

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?

Single sentence, front-loaded. While concise, it sacrifices informativeness; a few more words could improve clarity without losing brevity.

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?

Tool has no output schema and minimal description. Missing details on what constitutes a 'capability,' potential filtering, or pagination. The description is incomplete for effective use.

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 description omits any explanation of the two parameters (npub, dpop_token). The description adds no value beyond the schema.

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

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

Description states 'List every capability for semantic intent-matching.' The verb 'List' and resource 'capabilities' are specific. However, it does not differentiate from siblings that might also list items.

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 guidance on when to use this tool versus alternatives. No context or exclusion criteria provided.

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

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

With no annotations provided, the description carries the full burden. It states 'Free — no credits required,' which is helpful cost information. It describes the return structure but could be more explicit about read-only nature and required permissions.

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: one for purpose, one for detail and cost. No extraneous words. Front-loaded with the main action.

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

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

Given the tool has no parameters and an output schema (context indicates yes), the description sufficiently covers what an agent needs: what it does, what it returns, and cost. No gaps.

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 has zero parameters, so no parameter documentation is needed. The description adds value by explaining the output fields. Baseline for 0 params is 4, and the description meets 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?

Description clearly states 'List all available constraint types and their parameter schemas.' It specifies the returned fields (type, category, description, parameter specs) and context (pricing pipeline). The name itself is descriptive, and no sibling tool offers identical functionality.

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 does not explicitly state when to use this tool versus alternatives. It implies it's for exploring constraint types for the pricing pipeline, but lacks guidance on prerequisites or scenarios where this is the best choice.

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

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

With no annotations provided, the description carries the full burden. It discloses ordering (newest first) and output details (times_redeemed/total_uses progress bar), but does not explain what 'proof' means or authentication requirements in depth.

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

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

The description is concise with three sentences, each adding value: purpose+ordering, output rendering hint, and access restriction. No wasted words.

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

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

Given the tool's simplicity (list with one param and output schema), the description covers core aspects: what is listed, output details, and access scope. It could mention sibling differentiation (vs. cypher_list_my_coupons) and clarify the parameter, but overall it is sufficiently complete.

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

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

The input schema has one parameter (dpop_token) with 0% coverage in the description. The description does not mention or explain this parameter, leaving agents without guidance on its purpose or value.

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

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

The description clearly states the tool lists every coupon minted by the operator, in newest-first order. This distinguishes it from siblings like cypher_list_my_coupons implicitly, as it specifies 'this operator' rather than the current user.

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 notes the tool is restricted to operators and requires proof, setting clear usage context. However, it does not explicitly state when not to use it or name alternative tools for non-operators.

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

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

With no annotations, the description discloses that the tool returns both active and exhausted redemptions with per-row status values (active, window_closed, patron_limit, total_limit). It also states it's free and requires proof, which adds transparency. It does not mention side effects or rate limits, but the read-only nature is implied.

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

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

The description is concise with three short sentences. It front-loads the purpose and adds key details (return status values, cost, authentication) without waste. Every sentence provides value.

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

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

Given the presence of an output schema (not shown), the description does not need to fully detail all return fields. It covers the important status field and the auth requirement. The only gap is the dpop_token parameter, but overall it is fairly complete for a list operation.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'npub' as required with proof, but does not explain the dpop_token parameter at all. The dpop_token is optional with a default, but no meaning is given. The description adds minimal value beyond the schema.

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

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

The description clearly states that the tool lists coupons redeemed by a specific patron on a specific operator. This distinguishes it from the sibling cypher_list_coupons, which likely lists all coupons. However, it does not explicitly name the alternative.

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 indicates that the tool is free and requires proof of npub, giving a usage context. However, it does not provide explicit guidance on when to use this versus alternatives like cypher_list_coupons, or when not to use it.

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

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

With no annotations present, the description must fully communicate behavioral traits. It only states 'list' implying a read operation, but fails to disclose whether records are ordered, how 'recent' is defined, or any side effects. An agent would lack understanding of side effects, safety, or data recency.

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

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

The description is a single focused sentence with no superfluous words. It is front-loaded and to the point.

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?

Despite the presence of an output schema, the description lacks important context: ordering direction, pagination behavior, maximum allowed limit, and definition of 'recent'. These gaps reduce completeness for a list operation.

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 the description adds no new meaning beyond the schema's parameter descriptions. The schema already explains limit and status filter. Baseline 3 is appropriate.

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

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

The description clearly states the action (list), the resource (Bitcoin notarization records), and a temporal qualifier (recent). This distinguishes it from sibling tools like cypher_get_notarization_proof (single record) and cypher_notarize_ledger (creation).

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention contexts where it is appropriate, prerequisites, or situations to avoid. Without such information, an agent cannot make an informed selection.

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

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

No annotations exist, so the description should fully disclose behavior. It only mentions 'Operator-only' and the action, omitting authentication needs, error behavior, or output details. Insufficient for a tool with no annotations.

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

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

The description is one sentence with no redundancies. However, it is too brief and sacrifices clarity for conciseness.

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?

Despite having an output schema, the description fails to explain what 'query keys' are, the format of results, or operational context (e.g., prerequisites). Poorly covers needed context given no annotations.

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

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

Schema description coverage is 50%. The description adds meaning for npub (labeling it required) but says nothing about dpop_token. Overall, minimal added value beyond the schema.

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

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

The description clearly states the tool lists an operator's published query keys, using a specific verb and resource. It distinguishes from siblings like cypher_get_query and cypher_create_query.

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 specifies 'Operator-only', implying a constraint on who should use it, but does not provide explicit when-to-use or alternatives guidance. Missing exclusions or scenarios.

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

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

No annotations provided, and the description does not disclose any behavioral traits beyond creation. Lacks information on side effects, authorization requirements, or idempotency, which is critical for a mutation 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?

Single sentence, no fluff, but could benefit from a bit more detail. Effective and front-loaded.

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?

Despite having an output schema, the description is insufficient for a creation tool with 7 parameters. It does not explain return values, constraints, or typical use cases, leaving gaps.

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 86%, so the schema already defines parameters well. The description adds no additional meaning beyond stating the tool creates a coupon.

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

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

The description clearly states the action (Create) and the resource (operator-owned discount coupon), distinguishing it from sibling tools like cypher_delete_coupon and cypher_update_coupon.

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 guidance on when to use this tool versus alternatives such as cypher_update_coupon or cypher_delete_coupon. The description only states the action without context.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: it's operator-only, background, free, and slow. However, it does not describe side effects (e.g., whether it creates a Bitcoin transaction) or the return value, which is a gap.

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

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

Three concise sentences, each adding meaningful information (purpose, operator-only, timing, cost). No redundant or vague language.

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

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

Given zero parameters and the existence of an output schema (not shown but declared), the description covers the essential aspects: what it does, who can use it, timing, and cost. However, it does not explain whether the tool returns immediately or after confirmation, which could affect agent decision-making.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds no parameter info, which is appropriate since there are none to describe.

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

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

The description clearly states the tool builds a Merkle tree of all patron balances and submits the root to Bitcoin via OpenTimestamps. The verb 'build and submit' is specific, and the resource 'ledger notarization' is distinct from sibling tools like cypher_check_balance or cypher_list_notarizations.

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 specifies that it is an operator-only background task and mentions the confirmation time (1-6 hours). This provides context on when to use it (operator) and expectation on duration, but does not explicitly state when not to use it or mention alternative tools.

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

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

The description implies a write operation but does not disclose side effects, permission requirements, or processing details. With no annotations provided, the burden is high but unmet.

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?

Single sentence with no wasted words, though it could benefit from a brief qualifier about the Porter role.

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?

Lacks explanation of return values, the purpose of 'npub' and 'dpop_token' parameters, and the broader context of issue rejection recording.

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 60% (3 of 5 params described). The description adds no additional parameter meaning beyond the schema, so baseline score 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 clearly states the action ('Record') and the reason ('why Porter rejected an issue'), but does not distinguish from sibling tools like 'cypher_record_triage'.

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 guidance on when to use this tool versus alternatives; no context about prerequisites or when not to use it.

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

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

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the tool describes the ecosystem and is free, but omits details such as output format, side effects, authentication needs, or any constraints. The brief description is insufficient for an agent to understand implications.

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

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

The description is extremely concise at two short sentences. The first sentence clearly states the core purpose, and the second adds a minor note about cost. No unnecessary words or redundancy.

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

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

Given the tool has no parameters and an output schema exists, the description is adequate but minimal. It explains the high-level purpose but does not clarify what 'describe' means structurally or how it fits among many similar oracle tools. The lack of usage guidelines reduces 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 has no parameters, so the schema is trivially covered. The description adds no parameter-level details, but none are needed. Baseline of 4 is appropriate because there is nothing missing.

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

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

The description uses the specific verb 'Describe' and identifies the resource ('DPYC ecosystem') and means ('via the Oracle'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools that perform specific actions like checking balances or minting coupons.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as the many sibling tools or other oracle tools like 'cypher_oracle_network_advisory'. There is no mention of prerequisites or use cases.

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

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

No annotations are provided, so the description carries the burden. It states 'Free.' but does not disclose other behavioral traits such as read-only nature, idempotency, or any authorization requirements. For a simple getter with no parameters, the description is adequate but minimal.

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

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

Two short sentences with no redundant words. The description is highly concise and front-loaded with key 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?

Given no parameters and presence of an output schema, the description is sufficient. It covers the essential purpose and notes the cost aspect ('Free'). No missing elements for this simple retrieval tool.

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

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

The tool has zero parameters, so baseline is 4. No additional parameter information is needed, and the description adds nothing beyond the schema.

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

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

The description clearly states the verb 'Get' and the specific resource 'current DPYC certification tax rate', with the additional note 'Free.' which distinguishes it from sibling tools that perform other operations like account statements or adoption status.

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 explicit guidance on when to use this tool versus alternatives, but the simple nature implies use whenever the tax rate is needed. Lacks when-not or alternative mentions.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. The description only says 'Free.' and does not indicate whether the operation is read-only, any rate limits, authentication requirements, or side effects. The behavioral profile is essentially absent.

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

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

The description is a single sentence, which is concise and front-loaded. It achieves clarity without extraneous words. However, it could be more informative without sacrificing brevity.

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

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

For a tool with no parameters and an output schema, the description is adequate but minimal. It does not explain what 'DPYC' means or what the onboarding instructions contain. The existence of an output schema reduces the burden, but the description still lacks context about the response and usage context.

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

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

The tool has no parameters (0), so schema description coverage is 100%. Baseline for no parameters is 4. The description correctly implies no input is needed, but does not add beyond that.

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

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

The description states 'Get DPYC onboarding instructions from the Oracle. Free.' which includes a specific verb ('get') and resource ('onboarding instructions'). However, the acronym 'DPYC' is not explained, which could cause confusion. Among sibling tools like 'cypher_oracle_about' and 'cypher_oracle_network_advisory', this tool is clearly distinct in its focus on how to join.

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 guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, context, or scenarios where this tool should be used over other oracle-related tools.

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

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

No annotations provided; description only says 'Free.' It does not disclose whether the tool is read-only, rate limits, data freshness, or side effects. The behavioral burden is not met.

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

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

The description is very concise with two sentences that front-load key information (action, resource, identifier, cost). However, it is too sparse and could include more detail without losing conciseness.

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?

Despite having an output schema, the description lacks usage context, parameter details, and behavioral transparency. For a simple lookup tool with 0% schema coverage and no annotations, it is insufficient for complete understanding.

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?

Parameter 'npub' is documented only as a required string in the schema with 0% schema coverage. The description adds no meaning about format, length, or example, failing to compensate for the lack of schema descriptions.

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

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

Clearly states the tool looks up a DPYC community member by npub, but does not differentiate from similar sibling tools like cypher_get_nostr_profile which may also look up by npub.

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?

Minimal usage guidance: no mention of when to use this tool versus alternatives, no prerequisites or scenarios. Only 'Free.' indicates cost, but not when to use.

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

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

No annotations provided, so description must convey behavioral traits. It states 'Free' (cost implication) and 'Get' (read operation). However, no details on side effects, authentication, or rate limits. Given the tool has no parameters and is a simple advisory retrieval, the description is minimally adequate but lacks depth.

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?

Description is a single short sentence with no unnecessary words. It efficiently conveys the core action and a key attribute (free).

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

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

For a tool with no parameters and an output schema, the description is brief but omits details about the content of advisories or output format. It is sufficient for a simple call but could be more informative.

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?

Tool has zero parameters with 100% schema description coverage. Baseline for zero parameters is 4 per rubric. Description adds no parameter information, but none is needed.

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

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

Description states 'Get active network advisories from the Oracle.' This clearly specifies the verb (Get), resource (network advisories), and source (Oracle). The tool is distinct from siblings like cypher_oracle_about or cypher_oracle_get_tax_rate.

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 guidance on when to use this tool versus alternatives. The description only mentions it is free but does not indicate prerequisites, context, 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.