cypher-mcp

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 the tool is free and requires proof of ownership, but it does not cover error handling, rate limits, or other 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 concise and front-loaded, providing key information without unnecessary words. It is well-structured but could be slightly more 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 presence of an output schema, the description adequately covers the purpose, returned data, cost, and authentication. It does not mention pagination or limits, but overall it is complete for a read-only 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%, so the baseline is 3. The description adds context about npub and dpop_token (proof of ownership) but does not significantly enhance understanding of the parameters 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 generates a patron's account statement and lists the returned data. It distinguishes from the Authority tax balance but does not explicitly differentiate from siblings like 'cypher_account_statement_infographic'.

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 (patron spending account, not operator balance) and prerequisites (proof of npub ownership). It does not explicitly mention alternatives 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 provides key behavioral details: cost of 1 api_sat per call, verification via 'debit_or_deny', and the output being a dark-themed SVG with specific components. It does not cover failure cases or side effects, but overall adds substantial transparency.

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

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

The description is concise at four sentences, front-loading the core action. Every sentence adds value, though some internal structure like bullet points could improve readability. No superfluous content.

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 adequately lists the graphic components (balance hero, metrics cards, etc.) and includes cost and verification context. No obvious gaps for a generative 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%, so baseline is 3. The description adds minimal additional meaning beyond the schema; for example, it restates the days parameter default but does not elucidate format or constraints 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 clearly states it generates a visual SVG infographic of an account statement, distinguishing it from the sibling 'cypher_account_statement' which returns data in a different format. The verb 'generate' and noun phrase 'visual SVG infographic' provide a specific resource and action.

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

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

The description mentions cost and verification but does not explicitly state when to use this tool versus alternatives like 'cypher_account_statement'. It implies use when a visual graphic is desired, but lacks explicit when-not or exclusion criteria.

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 disclose behavior. It states the tool is 'Free' and 'Polls the Authority MCP-to-MCP', indicating a read-only, network-dependent action. It does not mention side effects, authorization needs, rate limits, or whether the polling is synchronous.

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 two short sentences. Each sentence provides distinct information: the main action and additional context (free, polling, possible statuses). No redundancy, and the primary purpose is 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?

Given no annotations and an output schema that exists but isn't shown, the description provides a reasonable overview but lacks parameter explanations and details on output format. It mentions possible statuses, which is helpful, but does not cover required vs optional parameters or behavior nuances.

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%, yet the description does not explain the parameters 'dpop_token' or 'authority_npub'. 'authority_npub' is hinted at by 'chosen Authority', but 'dpop_token' is completely ignored. The description adds no value beyond the schema in explaining parameter meaning.

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 adoption-request status for an operator at an authority. It lists possible statuses (pending/approved/rejected/provisioned), which adds specificity. However, it does not explicitly distinguish from similar sibling tools like 'cypher_request_adoption' or 'cypher_get_operator_onboarding_status', slightly reducing clarity.

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 vs alternatives, or what prerequisite steps (e.g., having made an adoption request) are needed. The context for invoking this tool is implied but not stated.

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

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

Annotations are absent, so the description must carry behavioral context. It states 'Record' (write operation) but does not disclose whether it overwrites existing anchors, auth requirements, rate limits, or side effects. This is insufficient for an agent.

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

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

The description is a single, efficient sentence with no fluff. It is appropriately front-loaded, but its brevity trades off completeness. Still, it earns its place.

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

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

With 5 parameters, no output schema, and no annotations, the description is too minimal. It does not explain the behavior for write operations, what happens on conflict, or the role of optional parameters. More context is needed for safe agent 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 description coverage is 60% (3 of 5 parameters have descriptions in schema). The tool description adds no additional meaning to the parameters. Parameters like npub and dpop_token are not explained, leaving gaps that the schema does not fill.

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 'Record where a symbol lives so future triage scopes its grep,' which is a specific verb-resource pair. It distinguishes the tool's purpose from siblings like cypher_index_symbol or cypher_symbol_provenance by focusing on anchoring a symbol's location for grep scoping.

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 usage when recording a symbol's location, but no context on prerequisites, conflicts, or preferred scenarios compared to sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Record' which implies mutation, but it does not mention authentication requirements, side effects, overwrite behavior, validation, or what happens on conflict. The schema's severity parameter adds slight context, but the description itself is nearly silent on 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?

The description is a single well-formed sentence with no fluff or repetition. It is appropriately front-loaded, though it may be too terse to be fully 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 the tool's complexity (five parameters, no annotations, no output schema, and a large sibling set), this one-line description is insufficient. It does not explain return behavior, prerequisites, or how this assertion tool relates to guarding, listing, or checking invariants.

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 adds no parameter-level meaning beyond the input schema. Schema coverage is 60% (three of five parameters have descriptions), leaving npub and dpop_token unexplained, and the description does not compensate for this gap or clarify the relationship between parameters like name and rule.

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

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

The description states a clear action ('Record') and a specific resource ('enforceable code invariant'), which communicates the tool's primary purpose. However, it does not distinguish this tool from closely related siblings 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?

The description provides no guidance on when to use this tool, no exclusions, and no mention of alternatives. It is a bare statement of what the tool does without any context for selection among the many invariant-related sibling tools.

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

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

No annotations are present, so the description must fully disclose behavioral traits. It indicates a write operation ('Record') and mentions 'unverified provenance', but fails to describe permissions required, side effects (e.g., data persistence), error conditions, or response behavior. The governance implications of recording rationale are not addressed.

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 conveys the core purpose efficiently. However, it could benefit from a slightly more structured format (e.g., separating action from context) without adding verbosity.

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, no output schema, and no annotations, the description is insufficiently complete for an agent to use the tool correctly. It omits what the tool returns, how it interacts with other entities (e.g., GitHub issues via issue_number), and the meaning of 'unverified provenance' in terms of data integrity. The tool exists in a complex ecosystem of 80+ siblings, and the description provides no integration 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?

Schema description coverage is 71% (5 of 7 parameters have descriptions), so the schema already provides meaning for most parameters. The description does not add any parameter-level detail beyond the schema. The two parameters without schema descriptions (npub, dpop_token) are set with defaults and their purpose is not clarified. The description's contribution to parameter understanding is minimal.

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, with the qualifier 'unverified provenance'. The verb 'Record' and resource 'rationale' are specific, but the term 'Journeyman' is domain-specific and may not be universally understood, slightly reducing clarity. It distinguishes from siblings like 'cypher_assert_invariant' which focus on recording invariants, but the differentiation is implicit.

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'. The description does not specify prerequisites, contexts, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the query intent, but does not disclose whether the operation is read-only, what kind of changes are reported, whether any side effects occur, or what the response format is. This is a significant transparency gap for a tool that likely reads data.

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 no filler or repetition. Every word contributes to the meaning, making it highly concise and easy 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 the absence of annotations and output schema, the description should provide more context about the return value, scope of changes, or edge cases. It only states the basic action, leaving the agent guessing about what precisely is returned or how optional parameters affect behavior. This is incomplete for a tool in a family of audit utilities.

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 reinforces the two required parameters (name as 'capability' and since_ms as 'since a given time'), which aligns with a 50% schema coverage. However, it adds no extra meaning for the optional parameters (npub, dpop_token) and does not go beyond what the schema already states. Since coverage is exactly 50%, a neutral 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 the tool's function with a specific verb ('Answer') and resource ('what changed on a capability'), and the temporal qualifier ('since a given time') distinguishes it from other audit siblings like cypher_audit_what_contradicts or cypher_audit_who_authorized. It leaves no ambiguity about the tool's core 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?

The description implicitly tells the agent when to use it: when a change history over time is needed for a capability. The 'since' phrasing clearly differentiates it from alternative audit tools, though it does not explicitly mention exclusions or alternative tool names. This is sufficient for typical 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states what the tool answers. It does not disclose whether it is read-only, what it returns (e.g., list, boolean), whether it requires authentication, or any side effects. This is a significant gap for a 4-parameter audit 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 with no wasted words, but it is under-specified. It is concise but lacks structure that would help an agent understand the tool's scope or parameters.

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?

This tool has no output schema, no annotations, and only 50% parameter coverage in the schema. The description does not explain return values, the meaning of 'contradicts', how to specify a capability, or the role of optional parameters like npub and dpop_token. Substantial contextual gaps remain.

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% (name and as_at_ms are documented; npub and dpop_token are not). The description adds no parameter-level information, so it does not compensate for the two undocumented parameters. It adds no meaning beyond what the schema already provides.

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

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

The description uses a specific verb ('Answer') and identifies the resource ('what contradicts a capability's assertions or guarding invariants'), which differentiates it from sibling audit tools like cypher_audit_what_guards or cypher_audit_what_changed_since. However, 'what contradicts' is somewhat ambiguous—it could mean listing contradictions or checking a particular contradiction—but it still conveys the core intent.

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 other audit tools, no exclusions, and no mention of prerequisites or alternatives. Usage is only implied by the tool's name and the generic phrasing.

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 says 'Answer' which implies a read-only query, but it does not disclose side-effect profile, auth requirements, or behavior for unknown capabilities. This is a significant gap for a tool with 4 parameters.

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 clear sentence, front-loaded with the action and object, containing no fluff. It is concise and well-structured for its limited content, though the brevity leaves out important details.

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 output schema, no annotations, and 4 parameters, this description is too thin. It does not explain what 'sources' means, the return format, or the roles of the optional parameters. Sibling audit tools likely provide richer context, making this one incomplete.

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 adds no meaning beyond the schema. It mentions 'capability,' but the schema already describes `name` as 'Capability name.' It does not explain `npub`, `as_at_ms`, or `dpop_token`. With 50% schema coverage, the description fails to compensate for the 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?

The description uses a specific verb ('Answer') and clearly identifies the resource ('a capability') and the result ('what sources ... derived from'). It distinguishes this tool from siblings like cypher_audit_what_changed_since (changes) and cypher_audit_what_contradicts (contradictions) by focusing on derivation origin.

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 given on when to use this tool vs the many audit siblings. It does not mention alternatives, exclusions, or prerequisites. Usage is only implied by the description's purpose, which is insufficient for a tool family with overlapping concerns.

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 carry the full behavioral burden, but it only restates the query intent. It does not disclose whether the operation is read-only, how as_at_ms affects results, whether dpop_token is required, or what the return shape looks like.

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 no wasted words. However, it is somewhat too terse to be fully informative, though this is a conciseness strength rather than a flaw.

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 four parameters (including time-travel and auth tokens) and no output schema, a one-sentence description is incomplete. It omits return values, parameter semantics, and any behavioral or usage context, making it insufficient for reliable 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 description coverage is 50%, but the description adds no parameter meaning beyond the word 'capability,' which already maps to the required 'name' parameter. The optional npub, as_at_ms, and dpop_token parameters are left undocumented in both the schema and description, so 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 uses a specific verb ('Answer') and clearly identifies the resource ('which invariants guard a capability'). It distinguishes itself from sibling audit tools by focusing on the 'guards' relationship between invariants and a capability, which is unique among the cypher_audit_* family.

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 about when to use this tool versus alternatives. It does not mention exclusions or related tools like cypher_audit_what_contradicts or cypher_invariant_provenance, leaving the agent to infer usage solely from the tool name and one-line purpose.

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 does not disclose whether this is a read-only operation, any permission requirements, or output format. It only restates the core query without adding behavioral context beyond the name.

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 eight words, with no unnecessary words. However, the phrase 'authoritative why' is jargon that may require prior domain knowledge, slightly reducing clarity.

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 output schema and no annotations, the description is insufficiently complete. It does not explain return values, parameter usage beyond name, or when to invoke this tool. For a four-parameter audit tool, the agent would need more 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?

Schema description coverage is 50% (two of four parameters lack descriptions). The description only implies that 'name' refers to a capability, which the schema already states. It does not compensate for undocumented npub, as_at_ms, or dpop_token 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 states the tool answers a specific question: who authorized a capability's authoritative why. The verb 'Answer' and resource 'capability's authoritative why' convey the purpose. It distinguishes from sibling audit tools by focusing on the authorizer of the rationale rather than the rationale itself, though the phrasing is somewhat jargon-heavy.

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 no explicit guidance on when to use this tool versus alternatives like cypher_audit_why_exists or cypher_authorize_capability_why. Usage is only implied by the question it answers, with no exclusions or recommended 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that output includes PROV-attributed assertions and gaps, but it does not state whether the tool is read-only, how time filtering (as_at_ms) affects results, what authentication (dpop_token/npub) is required, or possible failure modes.

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: 'Answer why a capability exists with PROV-attributed assertions and gaps.' Every word contributes meaning, and there is no redundant or filler content.

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

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

Given that there is no output schema, no annotations, and only partial parameter documentation, the description should provide more operational context. It omits the purpose of npub/dpop_token, any usage caveats, and what 'gaps' means in practice, leaving the tool under-specified for safe and 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 only 50%, with name and as_at_ms already described in the schema. The tool description adds no parameter-level meaning and does not clarify the undocumented npub or dpop_token fields. For an agent to invoke this correctly, those parameters remain 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 uses a specific verb ('Answer') and resource ('why a capability exists'), and adds output detail ('PROV-attributed assertions and gaps'). This clearly distinguishes it from sibling audit tools like cypher_audit_what_changed_since or cypher_audit_what_contradicts, which focus on different questions.

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 use when you need to understand why a capability exists, but it provides no explicit when-to-use or when-not-to-use guidance. It does not mention any alternative tools or exclusions, leaving the agent to infer suitability from the name alone amidst many similar audit/provenance tools.

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

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

No annotations are provided, so the description carries full burden. It uses 'author' which implies a write operation, but does not disclose side effects, required permissions, or other behavioral traits. The lack of transparency is a significant 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?

The description is overly terse—a single sentence that barely explains the tool. While concise, it sacrifices clarity and structure. Every sentence should earn its place; this one does not provide enough 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 tool has 4 parameters, no output schema, and a large sibling context, the description is completely inadequate. It does not explain the purpose of the 'why' parameter, the effect of authoring it, or how to use the tool effectively.

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% (descriptions for 'why' and 'name' only). The tool description adds no additional parameter information. Parameters 'npub' and 'dpop_token' are undocumented beyond defaults. 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?

Description states the tool authors the 'authoritative why' for a capability, but the phrasing is vague and does not differentiate from similar tools like cypher_suggest_capability_why or cypher_explain_capability. The verb 'author' implies writing, but the resource and action are unclear without context.

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 given on when to use this tool versus alternatives. The sibling list includes cypher_suggest_capability_why and cypher_explain_capability, which might be related, but the description offers no comparison or 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 are provided, and the description gives no behavioral details beyond the basic action. It does not disclose whether the operation is destructive, reversible, idempotent, or what side effects occur. For a mutation tool with zero annotation coverage, this is a severe 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?

The description is a single sentence that is concise and front-loaded. However, it is too brief for the tool's complexity and could benefit from a slightly longer structure (e.g., listing the required parameters or adding a note about prerequisites).

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 insufficient. It does not explain return values, error states, or the effect of optional parameters. An agent would lack critical context for safe 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 description coverage is 50% (the two required params have descriptions in the schema, but npub and dpop_token have only defaults). The tool description adds no additional meaning or context for any parameter—it does not explain format, restrictions, or relationships 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 'Attach a capability to one of the symbols that implement it' uses a specific verb ('attach') and clearly identifies the resources (capability and symbol). It distinguishes this tool from siblings like 'cypher_bind_rationale_to_symbol' or 'cypher_anchor_symbol' by specifying the binding direction.

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 (e.g., 'cypher_upsert_capability' or 'cypher_what_realizes_capability'). There is no mention of prerequisites, when not to use, or context about symbol implementation.

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 does not disclose behavioral traits such as side effects, idempotency, or required permissions. For a tool that likely modifies state, this is insufficient.

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. However, it is extremely brief and could be expanded slightly 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 the complexity (4 parameters, no output schema, no annotations), the description is incomplete. It fails to explain return values, prerequisites, or the purpose of npub and dpop_token, leaving significant gaps for the agent.

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

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

Schema coverage is 50% (only symbol_fqn and decision_id have descriptions). The description adds meaning by stating symbol_fqn is a fully-qualified name and decision_id comes from assert_rationale, but npub and dpop_token remain unexplained. 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?

Description clearly states the action (attach rationale to symbol) and identifies the resource (code symbol). However, it does not differentiate it from sibling tools like cypher_assert_rationale or cypher_bind_capability_to_symbol, which might cause confusion.

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 implies it follows cypher_assert_rationale (via decision_id), but this is not explicit, leaving the agent unaware of 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 provided, the description bears full responsibility for behavioral disclosure. It only says 'Show,' implying a read operation, but omits any details about side effects, authorization needs, rate limits, or error behavior. The description is too terse to be 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?

The description is a single sentence with no wasted words. It is appropriately sized for a tool with few parameters and no complex concepts, though it sacrifices detail 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 no output schema, low schema coverage, and a moderate number of siblings, the description is too incomplete. It does not explain what 'patent grounding' means, what the tool returns, or any edge cases (e.g., invalid capability). The agent lacks sufficient context to use the tool reliably.

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 'name' has a description). The tool description adds no further parameter information beyond what the schema already states. The parameters 'npub' and 'dpop_token' remain completely unexplained, leaving their purpose 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 uses a specific verb and resource: 'Show a capability's patent grounding.' It is clear what the tool does in isolation, though it does not explicitly distinguish from siblings like cypher_link_capability_to_patent or cypher_list_patent_elements. The term 'patent grounding' is somewhat domain-specific but likely clear in context.

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. There is no mention of prerequisites, limitations, or when not to use it. The agent receives no help in deciding between this and similar sibling tools.

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

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

No annotations provided, so description carries full burden. It discloses return value (sats), ownership (operator's own funding), and cost (free). However, it does not explicitly state read-only nature or any authorization requirements, though implied by 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 concise (4 sentences) with no wasted words. It is front-loaded with purpose, then return value, consequence, and clarification. 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 no parameters and presence of output schema, the description sufficiently explains purpose, return value, and usage context (including when to use another tool). Complete for 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?

No parameters exist, so schema coverage is 100%. The description does not need to add parameter meaning. Baseline score of 4 is appropriate given the absence of 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 checks the operator's tax balance at the Authority, returns sats for certifying patron purchases, and distinguishes from patron balances. It uses a specific verb ('check') and resource ('authority 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?

The description explains when to use (to check operator's tax balance) and what happens when balance is zero (call purchase_credits). It also notes it's free. It does not explicitly exclude other tools but provides actionable 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?

Discloses that the tool is free, requires no credits, and that proof of npub ownership is needed to prevent enumeration. Although no annotations exist, the description provides relevant behavioral context for a read operation.

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 paragraphs with front-loaded purpose. Every sentence adds value, 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 full schema coverage and presence of an output schema, the description adequately covers purpose, usage, and behavioral context. No gaps identified for an agent to decide.

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 100%, so the schema already documents both parameters. The description adds minimal extra meaning beyond the schema, but the detailed param descriptions in schema suffice. 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 tool checks a patron's credit balance at this operator, using specific verb and resource. It distinguishes from the sibling tool 'authority_check_balance' by contrasting operator vs Authority 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 tells when to use ('Check a patron's credit balance') and when not to ('For the operator's own balance...use authority_check_balance instead'). Also notes cost (free) and prerequisite (proof of npub ownership).

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, so description carries full burden. It discloses cost ('Free — no credits required') and security requirement ('Proof of npub ownership is required'), adding context beyond the schema. Does not mention rate limits or error behavior, but provides key 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?

Very concise: four sentences with no wasted words. Front-loaded with the core purpose, followed by usage timing, cost, and security – an optimal structure.

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 3 parameters with full schema coverage and an output schema, the description sufficiently covers purpose, timing, cost, and security. It could mention typical response (e.g., status codes) but the output schema compensates.

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%, with detailed parameter descriptions in the schema. The tool description adds no extra meaning beyond what is already in the schema, meeting the baseline of 3.

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

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

The description clearly states the purpose: 'Check the payment status of a Lightning invoice.' It uses a specific verb ('check') and resource ('payment status'), distinguishing it from sibling tools like cypher_check_price or cypher_check_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 says 'Call after paying the invoice from purchase_credits,' providing clear when-to-use guidance. Also mentions cost and proof requirement, but does not specify when NOT to use or name alternative tools.

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

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

No annotations are provided, so the description must cover behavioral traits. It explains it's a preview (likely read-only) and lists what it shows (cost, constraints). It does not explicitly state there are no side effects or mention what happens if the tool_id is invalid. This is adequate but not thorough.

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 brief, three sentences, and front-loads the core purpose. No unnecessary words. It efficiently conveys key points.

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 (1 required) and an output schema (not shown), the description provides a functional overview but lacks details on return values or when to use this tool in a workflow. It is sufficient for basic use but not exhaustive.

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% (two parameters lack descriptions). The description only provides a high-level purpose and does not explain individual parameters. For example, 'npub' and 'dpop_token' are not described in the description, leaving the agent without guidance on their meaning.

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: 'Preview the effective cost of a tool call.' It specifies what is shown (base cost, constraint effects) and notes it's free. While sibling differentiation is not explicit, the tool's unique function as a cost preview among many cypher_ tools is evident.

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 'Free — no credits required,' implying it's safe to use without cost. However, it gives no explicit guidance on when to use this tool vs. other sibling tools or what prerequisites exist (e.g., which tool_id to use). Usage context is implied but not fully explained.

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 disclose behavioral traits. It clearly states the operation is free, has no side effects, does not evict the cache or touch relays, indicating a safe read-only check. It could be more explicit about the return value (e.g., boolean), but the output schema likely covers this. Score reflects good transparency with minor omission.

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 two sentences. The first sentence immediately states the purpose, and the second provides usage context and safety. Every sentence earns its place with no unnecessary 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?

For a simple check tool with 2 parameters and an output schema, the description covers purpose, usage scenario, and behavioral traits. It doesn't detail prerequisites or output format, but the schema and output schema suffice. Score 4 indicates it is nearly 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?

Schema coverage is 100%, so baseline is 3. The tool description does not add new information about the parameters beyond what the schema already provides (both are described as required with specific formats). The description adds context about the npub-proof flow, but that is incidental to parameter meaning. Score stays at 3.

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

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

The description uses a specific verb ('Check whether') and clearly identifies the resource (validity of a cached dpop_token). It distinguishes from sibling check tools by explicitly mirroring 'check_oauth_status' for the npub-proof flow, providing clear differentiation.

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 concrete use case: ask if a dpop_token will be accepted before a paid call to avoid wasting credits. It states the tool is free and has no side effects. While it doesn't explicitly list when not to use it, the mirroring hint offers some guidance. A score of 4 reflects clear context with room for explicit 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 carries the full burden. It discloses the basic purpose but lacks detail on side effects (e.g., does it change issue status?), idempotency, authentication (npub, dpop_token fields), or error conditions. The agent is left guessing about behavior beyond the simple claim action.

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 waste, but it could be structured to front-load more critical context. It is efficient, though borderline too short for the complexity.

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 8 parameters (5 required), no output schema, and no annotations, the description is too sparse. It fails to explain workflow context (turn-based agent system), parameter dependencies, or usage expectations, leaving significant gaps for an AI agent.

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

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

Schema coverage is 75%, but the description adds no value beyond the schema. It does not explain how parameters like npub or dpop_token are used, nor does it clarify the meaning of worked_by or activity values. The 25% undocumented parameters lack any description context, and the existing schema descriptions are adequate but not enriched.

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 ('mark an issue as actively being worked') and the resource ('issue'), and specifies the timing ('at the start of an agent's turn'). It distinguishes from sibling tools like cypher_report_issue (creating) and cypher_issue_provenance (tracking history).

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 guidelines are provided. There is no mention of when to use this tool versus alternatives, prerequisites (e.g., issue must exist), or exclusions (e.g., not for finishing work).

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 does not disclose any behavioral traits such as side effects, authentication requirements, rate limits, or whether the operation is read-only. The description is minimal and leaves the agent uninformed.

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 short sentence, but it is underspecified and lacks front-loaded key information. It sacrifices clarity 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?

With no output schema, the description should indicate the structure of the return value. It only says 'scope', which is vague. Given the complexity and number of sibling tools, the description is insufficient for the agent to understand the tool's full behavior.

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 1 of 3 parameters has a schema description (keyword). The description adds no extra meaning beyond the schema; it mentions 'intent keyword' but does not explain the 'npub' or 'dpop_token' parameters. With low schema coverage (33%), the description fails to 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 states a verb and resource but 'code-orienteering scope' is unclear and not standard terminology. It fails to explicitly distinguish this tool from many sibling tools that may also return scopes or context.

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 any sibling tools. The description does not mention any context or criteria for 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?

Without annotations, the description carries the full burden. It mentions that the tool is a write operation ('publish'), and provides constraints on parameter naming and param_schema format. However, it omits details on side effects, authorization beyond 'Operator-only', error handling, or rate limits, leaving gaps for an agent.

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 sentences. The first sentence states the core purpose, and the second provides essential usage details. No redundancy 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?

For a tool creating query templates with parameters, the description covers key constraints (operator-only, parameter binding, param_schema format). An output schema exists, so missing return value information is acceptable. Some details like default values or error cases are omitted, but overall it sufficiently informs an AI agent.

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

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

Schema description coverage is 89%, so the schema already documents most parameters. The description adds value by explaining the $name binding requirement and the param_schema format, which are not fully captured in schema descriptions. However, it does not elaborate on all 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 explicitly states 'publish a new named Cypher query template', which is a specific verb and resource. It clearly distinguishes from sibling tools like cypher_execute_query_by_key or cypher_list_queries, and additionally mentions 'Operator-only' scope.

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 the tool is for operators only, implying access restrictions, but does not explicitly state when to use this over alternatives (e.g., cypher_update_query, cypher_delete_query). No guidance on prerequisites or context is 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?

Discloses cascading to all patron redemptions, no-op behavior for references, and operator restriction. Lacks warning about irreversibility, but annotations absent so description carries burden.

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?

Very concise: two sentences plus restriction line. Front-loaded with action, no filler.

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

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

Covers side effects and auth, but missing preconditions (coupon existence, state) and error scenarios. Output schema present reduces need for return description.

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 parameter descriptions in schema (0% coverage). Description does not explain dpop_token or its relation to 'requires proof'. Agent lacks guidance on authentication 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?

Explicitly states 'Delete a coupon' with clear verb and resource. Distinguishes from siblings like update, mint, forget by describing cascade behavior.

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

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

Mentions restriction to operator with proof, but does not contrast with sibling tools like cypher_forget_coupon or when to use this hard delete vs soft alternatives.

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

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

With no annotations, the description carries the burden. It discloses the operation as a write to a sensitive vault, the requirement of ownership proof, and that it is free. It adds context about the scope (only one field) but does not detail reversibility or rate limits.

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

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

The description is concise (5 lines) with no wasted words. It front-loads the action and key points: effect, cost, requirement. Every sentence earns its place.

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

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

Given the presence of an output schema (not shown) and 100% schema parameter coverage, the description is fairly complete. It covers the operation, prerequisites, and side effects. It could mention suggesting prior retrieval of fields to know which to delete, but is still adequate.

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 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema; it only mentions 'Proof of npub ownership' which relates to dpop_token. No enrichment of field meaning.

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 'Remove a single patron credential field.' It uses a specific verb and resource, and distinguishes from sibling tools like cypher_update_patron_credential by emphasizing deletion of one field without affecting others.

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 usage when a single credential field needs to be removed, but does not explicitly state when not to use it or compare with alternatives like update or get fields. It mentions the prerequisite of proof of npub ownership 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?

With no annotations, the description carries full burden but only says it deletes, without disclosing side effects, irreversibility, or permission details beyond operator status. This is insufficient for a destructive operation.

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 wasted words. However, it lacks line breaks or front-loading of critical info; it is efficient but could be slightly more 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?

Despite having an output schema and moderate complexity (3 params), the description is too terse. It does not explain return values, error conditions, or what a catalog entry is, leaving significant gaps for the agent.

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

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

Schema description coverage is only 33% (one of three parameters described). The description adds no extra information about parameters like 'key' format or 'dpop_token' usage, failing to compensate for the low 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 it deletes a catalog entry by key, using a specific verb and resource. It also notes 'Operator-only', which distinguishes it from sibling tools like cypher_create_query or cypher_update_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?

The description explicitly restricts usage to operators, providing clear context. However, it does not mention when not to use the tool or list alternatives, leaving some ambiguity about appropriate 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, so description carries full burden. It discloses: operator owns query text, user never sees raw Cypher, billing rollback on error, params are bound not interpolated. These are critical behavioral traits beyond the schema.

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 paragraphs, each with distinct purpose: purpose, usage alternative, billing note. Efficiently front-loaded with no redundant 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 tool has 4 parameters (one required), no annotations, but has output schema, the description covers the key concept, security (no direct Cypher), billing behavior, and parameter usage. It is complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 75% (3 of 4 params described). The description adds value by explaining that params are bound as Cypher $params and never interpolated, and must match the query's schema. Dpop_token lacks description but is likely for auth; some gap remains.

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 executes a published Cypher query by key, with specific verb 'execute a published, parameterized Cypher query'. It distinguishes from sibling tools that are named queries (e.g., cypher_find_airline_flights), noting those should be called 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?

Explicitly tells when to use (supply key and params) and when not to (if operator published a named tool, call that). Also provides billing context: charged only for delivered answer, no charge on failure (unknown key, invalid params).

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, and the description does not disclose behavioral traits such as whether the tool is read-only, any side effects, or required permissions. For a tool that likely queries data, this lack of clarity impacts agent decision-making.

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), but it sacrifices necessary detail. While brevity is valued, more information is needed to meet the needs of tool selection. It is not wasteful, but it is under-specified.

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 annotations and output schema, and that only one of three parameters is documented in the schema, the description fails to provide a complete picture. The tool's return value or behavior is not described, leaving significant gaps for the agent.

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

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

The input schema has 3 parameters but only 'name' has a description ('Capability name.'). The description adds no additional meaning to the parameters, and the optional 'npub' and 'dpop_token' are entirely unexplained, leaving their purpose 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 the verb 'explain' and the resource 'capability', and it adds two aspects: 'why it exists' and 'where it lives', which gives a specific purpose. It distinguishes from siblings like 'cypher_authorize_capability_why' which focuses on authorization, and 'cypher_upsert_capability' which is about creation/update.

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_suggest_capability_why' or 'cypher_authorize_capability_why'. There is no mention of prerequisites or disclaimers, leaving the agent without context for proper 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the action (Show) without revealing side effects, authentication requirements, rate limits, or whether it is read-only. While it implies a read operation, this is not explicitly 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?

The description is extremely concise, consisting of a single clear sentence. However, it could include slightly more information without becoming verbose, such as hinting at output or parameters.

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 output schema and three parameters (two undocumented), the description is incomplete. It fails to explain what the tool returns or the purpose of the optional parameters. The sibling tools list is large, and the description does not help differentiate this tool's specific role.

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 33% (only 'ref' has a description). The tool description adds no semantics for 'npub' and 'dpop_token', which remain unexplained. For 'ref', the schema already provides an example (e.g., 400), so the description offers no additional value over 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's purpose: to show what a patent reference numeral describes. It uses a specific verb (Show) and resource (patent reference numeral), and given the sibling tools like cypher_list_patent_elements and cypher_upsert_patent_element, this tool's function is distinct, though not explicitly differentiated.

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 guidelines are provided. The description does not specify when to use this tool versus alternatives, nor does it indicate any prerequisites or context for invocation.

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 only states it 'reports' but does not clarify if the operation is read-only, requires authentication (e.g., dpop_token), or has side effects. The agent lacks insight into permissions, idempotency, or resource 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, concise but at the expense of clarity. It front-loads the purpose but uses domain-specific terminology without elaboration. It could be restructured to include more information 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?

Given the tool has 2 optional parameters, no output schema, and no annotations, the description is too sparse. It does not explain the return value, expected behavior with missing parameters, or how the 'grep-scope shrinkage' metric is derived. The agent lacks sufficient information to use the tool reliably.

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 the two parameters (npub, dpop_token) at all. The agent cannot infer their meaning, expected format, or whether they are optional (defaults to empty string). This is a critical gap for correct invocation.

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 it reports how issues were located to measure grep-scope shrinkage, which is a specific verb-resource pairing. However, 'issues' and 'grep-scope shrinkage' are jargon not explained, making the purpose somewhat vague for an AI agent. It is not a tautology but lacks clear connection to the tool's domain.

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 sibling tools like cypher_adoption_status or cypher_check_balance. The description does not mention prerequisites, alternatives, or exclusions, leaving the agent without context for appropriate invocation.

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 implies a read operation but does not confirm safety, auth requirements, or side effects. Parameters like npub and dpop_token hint at auth but are unexplained.

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 short, but includes unnecessary 'named-tool smoke test' which adds no value. Front-loaded with the action, but could be cleaner.

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 simplicity, description is incomplete. No output schema or return format mentioned. Authentication parameters are unexplained. Essential context for an agent to use this tool correctly is missing.

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

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

Schema description coverage is 0%, so description must compensate. It only mentions 'two cities' but does not clarify expected format (e.g., airport codes vs city names) or explain npub/dpop_token. No added value over parameter names.

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 'Find airline routes between two cities', a specific verb+resource. The smoke test note is noisy but does not obscure purpose. Sibling tools are mostly unrelated, so no confusion.

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. No mention of prerequisites, limitations, or when not to use it. The description only states what it does, not 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 full burden. It reveals the cosmetic effect (coupon still exists, can be re-redeemed) and the free nature with npub proof requirement. It does not detail error cases or side effects but covers key behaviors.

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, all essential. The main action is front-loaded, with clarifying details following. No redundant 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 zero schema coverage and no annotations, the description explains the effect, permanence, and precondition. Output schema exists but is not shown; still, the description is fairly complete for a simple removal tool, missing only edge cases and return details.

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

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

Schema coverage is 0%, so description must compensate. It implies npub identifies the patron and coupon_id the coupon, but completely omits dpop_token. This partial coverage leaves a gap for one 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 'Remove a coupon from this patron's redemption list', specifying the action, target, and scope. It distinguishes from siblings like cypher_delete_coupon by noting it is 'cosmetic only' and the coupon still exists, helping the agent choose correctly.

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 that removal is cosmetic and the coupon can be re-redeemed, and notes the prerequisite 'requires proof of npub'. This gives good context, though it lacks explicit when-not-to-use or direct comparison to alternatives.

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 given, so description carries full burden. States deletion is as destructive as a write, which indicates behavioral implications. However, lacks details on side effects, idempotency, or error conditions.

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 concise: two sentences with clear front-loading. Every sentence adds necessary information without waste. Example of ideal 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 an output schema exists (not shown), return values need not be explained. Description covers destructive nature, ownership proof, and parameter roles. Still, could mention success/failure outcomes for 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?

Schema coverage is 100%, baseline 3. Description adds value by detailing dpop_token format requirements beyond schema (e.g., 'not base64, not NIP-98 framing'). This extra context justifies 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?

Clearly states the tool deletes vaulted credentials for a service and npub. Distinguishes between operator and patron npubs. However, does not differentiate from siblings like 'cypher_delete_patron_credential' or 'cypher_delete_coupon', which limits clarity.

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 context on when to use (forgetting credentials) and explains npub ownership proof requirement. But no explicit when-not-to-use or alternatives mentioned, leaving guidance incomplete.

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, but the description fully discloses the read-only nature, no cost, and the fact that it returns the latest metadata or an empty profile. No destructive behavior 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?

Three concise sentences, front-loaded with the action and purpose. Every sentence adds value without 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's simplicity (one parameter, no nested objects, output schema exists), the description is complete. It lists return fields and mentions the empty profile case.

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 compensates fully by explaining the 'npub' parameter as the public key whose profile to read. The schema only gives a default, but the description provides meaning.

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 reads a public Nostr profile for an npub, listing specific metadata fields. It effectively distinguishes from the sibling 'cypher_publish_nostr_profile' which is a write operation.

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?

Indicates the operation is free and requires no proof because data is already public. Implicitly tells when to use, though does not explicitly mention alternative tools for non-public data.

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 only states the tool generates a proof, offering no additional behavioral context (e.g., idempotency, required permissions, cost implications, or whether it modifies state). The description is minimal beyond the core action.

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

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

A single, well-structured sentence that front-loads the key action and resource. No unnecessary words; every part contributes to understanding.

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 an output schema (indicated by context), the description adequately explains the input purpose. It could mention that the tool is read-only, but the output schema likely covers return details. Parameters are fully documented in 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 100% (both 'npub' and 'notarization_id' have descriptions). The tool description adds no parameter-specific meaning beyond the schema, so 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 tool generates a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot. It uses specific verb 'Generate' and specifies the resource (patron's balance in notarized snapshot), distinguishing it from sibling tools like 'cypher_notarize_ledger' (creates notarizations) and 'cypher_list_notarizations' (lists them).

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

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

The description implies usage for obtaining proof of inclusion but does not explicitly state when to use this tool versus alternatives like 'cypher_check_balance' or 'cypher_check_proof_status'. No exclusions or alternative mentions are 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?

No annotations provided, so description carries full burden. It describes the output: shows which settings are configured/missing and how to deliver missing values. It does not mention side effects or authentication, but given it's a read-only report, the description 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?

Three informative sentences with no wasted words. Each sentence adds value: purpose, details of output, and alternative guidance.

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 is complete. It explains what the report contains and distinguishes from a related 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?

No parameters exist, so baseline is 4. Description adds context about the tool's scope (operator's configuration) but does not need to describe any 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 clearly states the tool 'Report this operator's configuration readiness' with a specific verb and resource. It distinguishes itself from the sibling tool 'get_patron_onboarding_status' by explicitly mentioning the alternative for patron-level 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?

Explicitly provides when to use this tool vs. alternatives: 'For patron-level credential status, use get_patron_onboarding_status instead.' This tells the agent when not to use this tool.

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

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

Despite no annotations, the description reveals key behaviors: it's free, requires proof of ownership, lists only field names (values never exposed), and notes sensitivity. Sufficiently transparent for a read-only operation.

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 brief and front-loaded with the core purpose. Every sentence serves a purpose, with no extraneous 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 simplicity and the presence of an output schema, the description covers essential aspects: what is returned, what is not, authentication, and security rationale. Complete for its 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?

Schema coverage is 100%, so baseline is 3. The description adds context that dpop_token proves ownership due to sensitivity, but does not add new parameter syntax or details 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 stored patron credential field names (not values), specifying what is returned and its purpose. It distinguishes itself from sibling tools by focusing on field names and timestamps, not values.

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 when to use the tool (verify configured fields and their age) and notes the authentication requirement (proof of npub ownership). However, it lacks explicit exclusions or alternatives from the sibling tool set.

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 read-only nature, requirement for proof of npub ownership via dpop_token, and reason for sensitivity. Lacks details on side effects or performance, but sufficient given the 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?

Description is 5 sentences, front-loaded with main purpose, then provides details on service types and requirements. Clear and well-structured, though could be slightly more 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?

Given the complexity of two service types and existence of output schema, description covers what the tool does, how it differs by service, and the proof requirement. No major gaps identified.

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% with parameter descriptions. Description adds context: explains dpop_token is a kind-27235 event signed by patron_npub for this tool and why proof is needed. This goes beyond schema, enhancing parameter understanding.

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 reports a patron's credential readiness, distinguishes between set-once and dynamic OAuth2 services, and specifies what is shown (configured/missing secrets or none needed). This is specific and differentiates 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?

Description implies usage context (checking credential readiness for a patron) and mentions service types, but does not explicitly state when not to use or compare with sibling tools like cypher_get_operator_onboarding_status or cypher_get_patron_credential_fields.

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 key behavioral traits: self-initialization behavior and the fact that no economic data is sourced from code. This adds transparency beyond a simple 'get' operation.

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?

Very concise: three short sentences that front-load the core purpose, then add necessary behavioral details. 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?

For a zero-parameter tool with an output schema, the description covers the main purpose and a critical behavioral nuance (self-initialization). Sufficient for agent to use 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?

Input schema has zero parameters, so baseline per rubric is 4. No parameter description needed; description provides no extra param info but none is required.

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'. The word 'Free' might be ambiguous but overall purpose is clear. Does not explicitly differentiate from related sibling tools like 'cypher_set_pricing_model' but the verb 'get' suffices.

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 context that the tool self-initializes a scaffold if no model exists and that there is 'No economic data from code.' However, it does not give explicit guidance on when to prefer this tool over alternatives 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, the description carries full burden. It discloses conditional behavior (edit_url included only if credentials are delivered, best-effort) and guarantees the raw template is always present. This gives the agent a good understanding of what to expect.

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 efficient: four sentences front-loading the core purpose, then adding key details about the edit_url. It is not verbose but covers necessary behavioral nuances without 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's simplicity (fetch by key) and the existence of an output schema, the description adequately covers what the agent needs: what is fetched, the conditional edit_url, and the fallback. It does not need to detail return fields since the output schema provides that.

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 low (33%), and the description does not explain parameters beyond the tool's purpose. The key parameter is left without context, and npub's requirement is mentioned in schema but not elaborated. The dpop_token is not described. The description adds minimal value over 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 'fetch' and the resource 'one catalog entry (template + schema + metadata)', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like cypher_list_queries (list) and cypher_create_query (create) by specifying it retrieves a single entry.

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 restricts usage to operators with 'Operator-only', and suggests a workflow: fetch with this tool, refine via edit_url in Neo4j Browser, then save with update_query. While it doesn't explicitly say when not to use it or list alternatives, the context is clear enough for an agent to decide.

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 is too brief to disclose behavior such as side effects, idempotency, permissions, or error conditions. It fails to inform the agent about important behavioral aspects.

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 short (5 words), which aids conciseness but sacrifices completeness. It is not well-structured to front-load critical information, and the brevity reduces its utility.

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 4 parameters, no output schema, and many sibling tools, the description is severely incomplete. It lacks information on return values, side effects, and relationship to other tools.

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 adds no extra meaning beyond the input schema. Two parameters (npub, dpop_token) lack schema descriptions, and the description does not cover them. With 50% schema coverage, the description should compensate but does not.

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 'Register a symbol an invariant guards' is grammatically awkward but conveys the core action: registering a symbol that an invariant guards. However, it lacks clarity and does not explicitly differentiate from siblings like cypher_anchor_symbol or 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 is provided on when to use this tool versus alternatives, prerequisites, or context. With many sibling tools, clear usage guidelines are missing.

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; description provides no behavioral details such as idempotency, destructiveness, authentication requirements, or side effects. Fails completely to add value beyond the minimal purpose.

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 is concise but underspecified. Lacks essential details; not well-structured for agent comprehension.

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 5 parameters, no output schema, and no annotations, the description is severely incomplete. No explanation of return values, side effects, or prerequisites.

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 60% of parameters; description adds no additional meaning for any parameter. Parameters 'npub' and 'dpop_token' lack schema descriptions and are not explained in the 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?

States verb 'Index' and resource 'code symbol', specifying association with a service. Adequately clear but does not distinguish from sibling tools like 'cypher_anchor_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?

No guidance on when to use this tool versus alternatives, no exclusions or context provided. Agent cannot determine appropriate 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?

With no annotations, the description must fully disclose behavior. It only says 'Explain an invariant and what it guards,' omitting details on output format, side effects (likely none), error handling, 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?

The description is a single sentence, which is concise, but it lacks necessary detail. It is not wasteful, but being too brief reduces usefulness.

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 three parameters and no output schema or annotations, the description is too sparse. It fails to explain the return value, the role of optional parameters, or how the tool fits into a workflow.

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% (name has a basic description). The tool description adds no parameter meaning beyond the schema. npub and dpop_token are left unexplained, so the agent has no guidance on how to use them.

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 explains an invariant and its guard, which is a specific action on a resource. This distinguishes it from siblings like cypher_assert_invariant or cypher_list_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 on when to use this tool versus alternatives. No mention of prerequisites, when not to use it, or comparison with similar 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?

Annotations are absent, so description carries full burden. Only states 'Fetch' indicating read-only, but fails to disclose authentication needs, error handling, or what the provenance chain includes.

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 extraneous words. Front-loaded with verb and 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?

Low complexity tool (fetch by repo and issue) but description lacks detail on provenance chain output, URL format, or expected behavior. No output schema. Incomplete for a developer unfamiliar with the domain.

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% (repo_name and issue_number described). Description adds no parameter meaning beyond schema; npub and dpop_token unexplained. 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?

Description clearly states the verb 'Fetch', the resource 'issue's GitHub URLs and provenance chain', and the purpose 'for browser click-through'. It distinguishes this from sibling tools like cypher_list_issues or cypher_link_issue_to_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 vs. alternatives. The description implies use for a single issue's provenance, but does not contrast with other provenance or issue 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, so the description must disclose behavioral traits. "Record" implies a write operation, but there is no mention of side effects, idempotency, or permissions needed for this action.

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 wasted words. It could benefit from more detail without being 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?

The tool likely creates a relationship, but the description omits critical context: what happens on duplicate, how to verify the record, or any prerequisites. With no output schema, the description should address these 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 50% with only name and consumer_repo described. The tool description adds no additional meaning beyond the schema. For a tool with 4 parameters and 50% coverage, the description should compensate but does not.

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 "record" and identifies the resources (service, capability), making the purpose clear. It also distinguishes from siblings like "cypher_upsert_capability" which creates/updates a capability itself.

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. Given many sibling tools, explicit context for when this action is appropriate would be beneficial.

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 carry full burden. It only states the basic action without disclosing side effects, authorization needs, or whether it is destructive. For a write-like operation, safety information is missing.

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

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

A single, well-structured sentence with no verbosity. Every word is meaningful, but conciseness does not excuse missing critical 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?

No output schema and minimal description. Agent cannot infer return value, errors, or side effects. With 4 parameters and multiple siblings, the description is too brief to fully guide 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 coverage is 50% (only name and patent_ref have descriptions). The description adds no parameter-level details beyond restating 'patent reference numeral.' It does not explain npub or dpop_token, leaving gaps not compensated by 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 'Ground a capability in a patent reference numeral' uses a specific verb and clarifies the resource (capability) and relationship (patent reference numeral). It is distinct from siblings like cypher_bind_capability_to_symbol or cypher_link_invariant_to_patent, though 'ground' is domain-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?

No guidance on when to use this tool versus alternatives like cypher_link_invariant_to_patent. There is no mention of prerequisites, context, or when not to use it. Given many similar sibling tools, this is a gap.

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 'Ground' which implies a state change or association, but offers no details on side effects, permissions, reversibility, or impact on existing links. This is insufficient for a likely 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, front-loaded sentence with no wasted words. However, given the tool's role and sibling context, it could benefit from slightly more detail without losing conciseness, but it's still 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?

No output schema exists, and 50% of parameters lack schema descriptions. The description should compensate by explaining return values, side effects, or parameter usage. It does not, leaving the agent underinformed about the tool's behavior and output.

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% (name and patent_ref have descriptions; npub and dpop_token lack descriptions). The description adds no extra meaning beyond the schema, merely echoing 'invariant' and 'patent reference numeral'. It does not help with the undocumented parameters, which have defaults but no semantic guidance.

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 an invariant in a patent reference numeral' clearly states the action (ground) and resources (invariant, patent reference numeral). It distinguishes from sibling tools like 'cypher_assert_invariant' and 'cypher_link_capability_to_patent' by focusing on linking an invariant 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?

The description provides no guidance on when to use this tool versus alternatives. Sibling tools include many linking operations (e.g., 'cypher_link_capability_to_patent', 'cypher_link_issue_to_capability'), but the description fails to specify conditions or prerequisites for using this specific tool.

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 behavioral transparency. It states the action ('attach') but does not disclose details such as idempotency, side effects, permission requirements, or error behavior. For a mutation tool, this is insufficient.

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 that delivers the core message without unnecessary words. It is front-loaded and efficient, earning its place.

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

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

Given the tool has 5 parameters (3 required) and no output schema, the description is too brief. It does not explain what 'attach' entails operationally, what constitutes a successful response, or how errors are handled. More context would be needed for safe and 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?

The input schema has 60% description coverage (3 of 5 parameters described). The description adds no parameter details beyond what the schema already provides, such as the meaning of 'capability_name' or the role of 'npub' and 'dpop_token'. This does not improve semantic clarity for the agent.

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 'Attach an issue to the capability it is about' uses a specific verb ('attach') and clearly identifies the resources ('issue' and 'capability'), making the tool's purpose unambiguous. It also distinguishes from sibling tools like cypher_link_capability_consumer and cypher_link_capability_to_patent, which link 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 provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusion criteria. Without context like 'use this when other linking tools are not appropriate', the agent lacks decision support for tool 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?

With no annotations, the description must fully disclose behavior. It implies a mutation (attaching a URL to an issue) but omits side effects, permissions required, or whether the operation is reversible.

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. However, it could be expanded slightly to improve clarity 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?

The description fails to provide adequate context for a mutation tool with no output schema and no annotations. It does not explain what 'attach' means operationally or what the result looks like.

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 adds minimal value beyond the schema: it recontextualizes 'pr_url' but ignores 'npub' and 'dpop_token' entirely. Schema coverage is 60%, but the description does not compensate for the 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?

The description clearly states the action (attach) and the resources (fix PR GitHub URL to its issue), distinguishing it from sibling link tools like cypher_link_capability_consumer. However, it could be more specific about what 'attach' entails.

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 similar linking tools. The description lacks context on prerequisites or alternatives.

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 does not disclose behavioral traits such as side effects, permissions required, or whether links can be overwritten. For a mutation tool, this lack of transparency is insufficient.

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 wasted words. It is front-loaded and easy to parse, though it could benefit from slightly 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?

The tool has 5 parameters, no output schema, and is a mutation operation. The description is too minimal to provide complete context; it does not explain return behavior, error conditions, or validation. More details are needed for adequate 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?

Schema description coverage is 60%, but the tool description only echoes the schema for two parameters (issue_number, symbol_fqn) without adding new meaning. Two parameters (npub, dpop_token) lack any description in both schema and description, providing no additional 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 purpose: linking an issue to a code symbol that caused it. The verb 'point' is specific, and the resources (issue, code symbol) are identified. However, it does not differentiate from sibling tools like 'cypher_link_issue_to_capability' or 'cypher_link_pr', leaving some ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, intended use cases, or scenarios where other sibling tools would be more 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, so the description carries the full disclosure burden. It explicitly states 'Free, no side effects,' discloses the inclusion of unregistered tools with 'registered: false', and explains the canonical-UUID design rationale (tool_id stays stable while mcp_name can change). It also discloses the live wire-surface diff behavior. The description adds substantial context beyond what any structured field would provide.

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 informative but somewhat verbose at ~200 words for a zero-parameter list tool. There's some redundancy: the 'unregistered' flag/drift concept is explained twice (once for UUID-missing tools via #174, once for wire-surface diff via #175). The core message could be tightened, though each section does add distinct 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?

This is a low-complexity zero-param tool with an output schema present. The description thoroughly covers what's returned, why it matters, how it's used by Reconcile, and the drift-detection behavior. It also explains behavioral nuances (UUID stability across renames) that an agent needs to interpret results correctly. Complete for this tool's purposes.

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?

This tool has 0 parameters and 100% schema coverage, so the baseline is 4 (no params means description needn't compensate). The description notes what the output array contains (tool_id, mcp_name, registered flag, top-level unregistered array), providing semantic context for the returned data despite no input 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 uses a specific verb+resource construction: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' It clearly distinguishes itself from siblings by focusing on the canonical identity mapping and UUID reconciliation, which no sibling tool name suggests.

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 it is 'The authoritative source for any client (Studio, agents, FE)' and that 'Reconcile uses this output to UUID-join against the stored pricing model.' It also names specific downstream consumers and clearly delineates what this tool does versus sibling identity/provenance 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, so description must disclose behavioral traits. It does not mention read-only nature, authentication requirements (dpop_token parameter hints at auth but not stated), pagination, or performance 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?

Extremely concise (single sentence), but lacks any structure or elaboration. Could be improved with brief parameter notes or usage context.

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 3 optional parameters and no output schema. The description does not clarify output shape, whether since_ms filters 'every' capability, or what 'capability' means in this domain. Insufficient for reliable 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 only 33% (since_ms described), but description adds no parameter information. The description does not explain how npub, since_ms, or dpop_token affect the listing, leaving agents to infer.

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 lists capabilities for 'semantic intent-matching', which distinguishes it from sibling tools like explain/upsert. However, it does not explicitly differentiate from similar list tools (e.g., cypher_list_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?

No guidance on when to use this tool versus alternatives like cypher_explain_capability or cypher_upsert_capability. The description is purely imperative.

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 behavioral burden. It explains the return contents (type, category, description, parameter specs) and notes it's free. No side effects or destructive actions are 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?

Three concise sentences: purpose, return details, cost. No fluff, every sentence is informative.

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 an output schema, the description doesn't need to detail return values. It sufficiently describes the scope and cost, making it complete for a list 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?

There are zero parameters, and schema coverage is 100%. The description adds no additional parameter info, but the baseline for no 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?

The description clearly states the tool lists all constraint types and their parameter schemas. The verb 'list' and resource 'constraint types' are specific, and no sibling tool duplicates this 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?

It explicitly says 'Free — no credits required,' indicating it can be used without cost. While it doesn't mention when not to use, the context is sufficient for such a simple tool.

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. States access restriction and data included, but lacks details on failure modes or side effects.

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?

Concise, three sentences front-loading purpose and data description. Lacks parameter explanation but otherwise 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?

Output schema is present but not detailed. Description covers purpose and data but omits parameter semantics and potential pagination or limits.

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%. The description does not explain the dpop_token parameter or how to obtain the required proof.

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 lists coupons minted by the operator, ordered newest first, and distinguishes from sibling tools like cypher_list_my_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?

Specifies that the tool is RESTRICTED to operators and requires proof, but does not mention when to avoid this tool or compare with alternatives.

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 disclose behavioral traits. It states 'list' (a read operation) but does not mention any side effects, permissions, pagination, or ordering. This is insufficient for a tool with 3 parameters.

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 short, which is efficient, but it sacrifices necessary detail. It packs no information beyond the name, so it is under-specified rather than appropriately 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?

Given the presence of 3 parameters, no output schema, and many sibling tools, the description fails to provide sufficient context. The agent cannot reliably determine how to filter invariants or interpret results.

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 low (33%), with only 'since_ms' having a description. The tool description does not explain the meaning or purpose of 'npub', 'since_ms', or 'dpop_token', leaving the agent without needed context for correct 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?

The description 'List every enforceable invariant' clearly indicates the action (list) and the resource (invariants), but it does not differentiate from sibling tools like cypher_assert_invariant or cypher_guard_invariant_symbol, which could be confused.

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 such as cypher_assert_invariant or cypher_guard_invariant_symbol. The agent is left to infer the context from the name alone.

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