personalbrain-mcp

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

With no annotations, the description carries full burden. It states that the tool is free ('no credits consumed'), requires proof of npub ownership, and explains the anti-scraping motive. It also clarifies data scope (purchase history, credit tranches, etc.) and what it is not (Authority tax balance), providing strong behavioral 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?

Three sentences, each serving a purpose: the first states the function and contents, the second clarifies scope vs Authority tax balance, the third covers cost and auth. No filler or repetition.

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

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

Complexity is moderate with 3 params and an output schema present. Description covers return contents, cost, authentication requirement, and scope distinction. Given the output schema handles detailed return structure, no significant 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 coverage is 100%, so the schema already documents all three parameters (days, npub, dpop_token) thoroughly. The description adds only general mention that proof of npub ownership is required (matching dpop_token) and doesn't add per-parameter semantics beyond the schema's detailed dpop_token documentation.

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 opens with 'Generate a patron's account statement at this operator' – a specific verb and resource. It enumerates contents (purchase history, credit tranches, per-tool usage breakdown, daily usage logs) and explicitly distinguishes from Authority tax balance, which differentiates it from sibling tools like brain_check_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 provides context: it's for the patron's spending account, not the operator's Authority tax balance, and notes that proof of npub ownership is required. This implies when-not and a prerequisite, but it doesn't name alternative tools for the excluded case (e.g., brain_check_authority_balance) or state explicit 'use this when' scenarios.

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

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

No annotations are provided, so the description carries the full burden. It discloses the cost ('Costs 1 api_sat per call'), the authentication flow ('Proof is verified by debit_or_deny before any cost is incurred'), and the output composition ('balance hero, metrics cards, health gauge, tranche table, and tool usage breakdown'). This goes beyond the schema, though it doesn't explicitly state whether the tool is read-only or describe 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 two sentences, front-loaded with the main purpose, followed by output details and cost/verification. Each sentence earns its place with zero waste. It is concise and well-structured.

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

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

The description is complete for a tool with an output schema and 3 parameters. It explains the return value (SVG with specific sections), the cost, the proof verification, and differentiates from a sibling tool. Given the output schema exists, the description need not elaborate on return value structure, and it doesn't omit critical 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 100%, so the baseline is 3. The description does not add any parameter-specific meaning; it only describes the overall output. Since the schema already documents each parameter thoroughly, no additional semantic value is provided, meriting a baseline score.

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

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

The description opens with a specific verb + resource: 'Generate a visual SVG infographic of your account statement.' It clearly distinguishes itself from the sibling brain_account_statement by stating that it 'Returns the same data as account_statement, rendered as a dark-themed SVG graphic,' making the purpose unambiguous.

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

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

The description implies when to use this tool by comparing it to account_statement: it provides the same data but in a visual SVG form. However, it doesn't explicitly say 'use account_statement for raw data' or list when-not conditions. The context is clear but not fully explicit, so a 4 is appropriate.

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

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

With no annotations, the description must bear the burden of behavioral disclosure. It does add the non-obvious detail that npub is required for credit billing, which implies a metered operation. However, it lacks other important behaviors like whether the file must exist locally, whether the operation is reversible, or any 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 two sentences long, front-loaded with the core action, and contains no fluff. Every word contributes 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?

Despite having an output schema and decent parameter coverage, the description is too sparse for a 6-parameter tool with no annotations. It omits context about default brain behavior, file requirements, and the exact nature of the attachment operation, leaving the agent with significant 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?

The schema already covers 83% of parameters with descriptions, including npub's billing purpose. The description reinforces the npub requirement but adds no new parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Add a file attachment to a thought.' This clearly distinguishes it from sibling tools like brain_add_url_attachment or brain_delete_attachment, as it focuses on attaching a local file to a thought.

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

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

No guidance is provided on when to use this tool versus alternatives. The close sibling brain_add_url_attachment is not mentioned, and there is no explanation of prerequisites or typical scenarios beyond the implicit need for a file attachment.

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

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

No annotations are provided, so the description carries the burden. It discloses a key behavioral requirement: 'Requires npub for credit billing,' which is non-obvious and useful. However, it does not describe the operation's side effects, error behavior, or expected return (though output schema exists). This is adequate but has gaps.

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

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

The description is two sentences, front-loaded with the action, and contains no fluff. Every word 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 tool's simplicity and the presence of an output schema, the description covers the essential purpose and a critical prerequisite (npub). It does not explain all parameters, but the schema covers those. Minor gap: it doesn't mention how the active brain is used, but that is not critical.

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 83%, so baseline is 3. The description emphasizes npub as required, which aligns with the property description, but adds no new semantic meaning beyond the schema. It does not explain dpop_token or the optional brain_id behavior beyond what 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 states a specific action: 'Add a URL attachment to a thought.' This clearly identifies the resource (URL attachment) and target (thought), and distinguishes it from sibling tools like brain_add_file_attachment. The additional npub billing note doesn't obscure the primary 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 clearly implies usage: to attach a URL to a thought. It also provides an important prerequisite: 'Requires npub for credit billing.' However, it does not explicitly mention alternatives or exclusions (e.g., when to use brain_add_file_attachment instead), so it lacks explicit when-not 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, the description carries the full burden. It discloses that the operation is free, that it polls MCP-to-MCP, and lists possible statuses. However, it omits authentication expectations, error behavior, and the meaning of the dpop_token parameter, so transparency is only partial.

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 compact and front-loaded with the primary purpose. The 'Free' note and the polling mechanism are essential and distinct, and the status list adds concrete value without unnecessary 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?

The output schema covers return values, so that is not needed here. The tool is simple, and the description conveys purpose and mechanism. However, missing parameter semantics and lack of explicit usage guidance make it only minimally complete for a tool with multiple sibling status-checkers.

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

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

Schema description coverage is 0%, so the description must compensate. It only indirectly references 'authority_npub' via 'chosen Authority' and does not explain 'dpop_token' at all. This fails to adequately document the two parameters, leaving the agent to guess their roles.

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 specific action ('Check') and resource ('this operator's adoption-request status') with a scoping location ('at a chosen Authority'). It differentiates from sibling status tools by explicitly naming 'adoption-request' and enumerating possible statuses.

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 some usage context: it is free, it polls the Authority MCP-to-MCP, and it targets adoption requests. However, it does not explicitly state when to use this instead of other status-checking sibling tools (e.g., brain_get_operator_onboarding_status, brain_check_proof_status) or mention any 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 discloses useful behavioral details: it auto-resolves wikilinks, leaves unresolved [[...]] literals and returns them, supports [[#<thoughtId>]] disambiguation, and specifies the credit-billing prerequisite. It does not mention idempotency or what happens if the target note does not exist, but the provided behavior is meaningfully 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?

The core purpose is front-loaded, and the longer guidance is organized under 'Note style' and 'Linking to other thoughts' headings. Each section earns its place by providing necessary formatting rules for a tool that generates note content, though it is slightly verbose.

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

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

Given the output schema and 80% schema coverage, the description covers the operation, prerequisite, and content-formatting conventions well. It would benefit from an explicit comparison to create/update siblings and a little more detail on edge-case behavior, but it is essentially complete for an append-to-note tool.

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

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

Schema description coverage is 80%, so baseline is 3. The description adds substantial value for the markdown parameter by explaining wikilink syntax, external link formatting, bold usage, and unresolved-link handling, and it clarifies npub's role for billing. The dpop_token parameter remains unexplained, but the description goes well beyond schema basics.

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 opens with 'Append content to an existing note', which clearly states the verb, resource, and scope. It differentiates from sibling create/update tools through the word 'append', though it does not explicitly name those alternatives.

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

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

The description gives a prerequisite ('Requires npub for credit billing') and implies the tool is for appending to a note that already exists. However, it does not explicitly state when to prefer this over brain_create_or_update_note or brain_update_thought, and the style guidance concerns content formatting rather than 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 provided, the description fully discloses critical behaviors: incomplete name index can cause false negatives, empty match sets don't prove absence, and ID matching is reliable. It also warns against unsafe CREATE/MERGE without ID verification, and supports a limited Cypher subset.

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 moderately lengthy but well-structured, front-loading the purpose and credit billing requirement, then detailing syntax and important limitations/warnings. Each sentence adds value, though the warning 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?

For a complex tool with write/delete capabilities, the description covers billing, syntax, safety caveats, and confirmation for DELETE. An output schema exists, so return values need not be described. It lacks details on dpop_token or transaction behavior, but is otherwise thorough.

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 80%, but the description enriches the 'query' parameter by explaining BQL syntax and the unreliability of name matching. It adds meaningful context beyond the schema, though other parameters like dpop_token remain undocumented.

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

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

The description clearly identifies the tool as the 'Primary tool for pattern-based operations on TheBrain' and specifies it accepts BrainQuery (BQL), a Cypher subset. This distinguishes it from sibling CRUD tools by emphasizing general pattern-based operations.

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

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

Provides explicit guidance on when not to rely on name-based matching and recommends using get_thought for ID-based checks to avoid erroneous CREATE/MERGE. Also notes the billing requirement (npub). However, it does not directly compare use cases with most 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. It discloses that this is a check (read-only) that returns 'the sats available' and is 'Free.' It also explains the operational consequence of a zero balance and directs the operator to purchase_credits. This is solid behavioral transparency, though it doesn't describe the output structure (output schema exists).

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

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

The description is four sentences, each adding meaningful context: the core purpose, what the balance represents, the consequence of zero, and a key distinction from patron balances. It is front-loaded and free of filler, making it easy for an agent to parse.

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

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

The tool is simple with no parameters, and the description covers what it returns (sats available), what it is for (certifying patron top-ups), what to do when it's exhausted (purchase_credits), and a critical distinction (operator vs. patron balance). This fully addresses the agent's needs for invocation and decision-making.

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

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

The tool takes zero parameters, and the schema has no properties. The description adds meaning by explaining that the 'balance' refers to operator funding for certifying patron purchases, not a patron balance. Since there are no parameters to document, the description adequately conveys the semantic of what is being checked.

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 opens with a specific verb+resource ('Check this operator's tax balance at the Authority') and further clarifies the exact meaning of the balance (sats available for certifying patron credit purchases). It explicitly states it is the operator's own funding, not a patron balance, which distinguishes it from siblings like brain_check_balance. This is a clear, unambiguous 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 provides context for when this tool is relevant: when the balance reaches zero, patron top-ups cannot be certified and the operator must call purchase_credits. It also differentiates this from a patron balance check, implying when to prefer this tool over alternatives. However, it does not explicitly name sibling tools or provide a 'when not to use' statement.

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 and does well: it states the tool is free (no credits required), requires proof of npub ownership to prevent enumeration, and clarifies this is a balance check rather than a write operation. It doesn't disclose failure modes or rate limits, but the disclosed behaviors are valuable.

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

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

The description is three short paragraphs with the main purpose front-loaded. Each sentence earns its place: purpose, distinction from alternative, and cost/auth requirements. No wasted words.

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

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

Given only 2 parameters and the presence of an output schema, the description covers all essential context: what the balance represents, when to use this tool vs the sibling, cost implications, and authentication requirements. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema already includes detailed descriptions for both npub and dpop_token (including dpop_token format and constraints). The description adds no parameter-specific details beyond what the schema provides, 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 'Check a patron's credit balance at this operator' with a specific verb and resource, and explicitly distinguishes it from the operator's own balance tool by naming the alternative. This makes the tool's purpose unambiguous and differentiates it from siblings like brain_check_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 provides explicit guidance: 'For the operator's own balance at the Authority... use authority_check_balance instead.' It also explains the context of the patron's spending balance and notes the tool is free and requires proof of npub ownership, giving clear when-to-use and cost/auth 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 provided, the description discloses important behavioral traits: 'Free — no credits required' and the security rationale for npub ownership proof. It adds context beyond the basic check operation, though it doesn't describe potential error responses or specific statuses returned. This is valuable but not exhaustive.

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 only three sentences, front-loaded with the main purpose, and includes critical caveats without any fluff. Every sentence earns its place, making it very concise and well-structured.

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

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

Given the tool's moderate complexity, full schema coverage, and presence of an output schema, the description covers the essential workflow (when to call), prerequisites (npub proof), and cost (free). It is complete for an agent to correctly select and invoke the 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% with detailed parameter descriptions, so baseline is 3. The description adds additional meaning by tying invoice_id to purchase_credits output and explaining why npub ownership proof is needed. This goes slightly beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Check the payment status of a Lightning invoice.' It distinguishes itself from siblings by specifying the exact resource (Lightning invoice) and the workflow context (after purchase_credits). This is specific with a verb and resource, making it easily distinguishable.

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 explicit usage context: 'Call after paying the invoice from purchase_credits.' It also mentions the requirement of npub ownership proof. However, it does not explicitly state when not to use this tool or mention alternatives, so it doesn't reach a 5.

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

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

With no annotations, the description must carry behavioral disclosure. It reveals key traits: the call is a 'preview' (non-executing), shows base cost and constraint effects, and is free (no credits required). It does not fully describe limitations or authentication needs, but the essentials are covered.

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

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

The description is two sentences: the first front-loads the purpose, the second elaborates on output and cost. Every part is informative, with no fluff or repetition of schema 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?

The description provides enough context for an agent to understand the tool's purpose, output, and cost implications. Since an output schema exists, return values are covered. However, it does not explicitly distinguish from brain_get_pricing_model, which could raise confusion in the sibling tool list.

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% (tool_id and tool_kwargs have descriptions). The description adds context about 'constraint effects' and 'tool call parameters,' which hints at tool_kwargs usage. However, it does not explain npub or dpop_token, which have no schema descriptions, leaving a gap for optional but potentially relevant 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's function: 'Preview the effective cost of a tool call.' It specifies the verb (preview), resource (cost of a tool call), and what it outputs (base cost and constraint effects). This distinguishes it from siblings like brain_get_pricing_model or brain_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?

The description conveys clear usage context: use this to preview cost before executing a tool call. It also notes 'Free — no credits required,' implying a safe, low-cost way to estimate pricing. However, it does not explicitly mention alternatives or when not to use it, which stops it from being a 5.

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

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

With no annotations, the description handles transparency well by stating 'Free, no side effects — does not evict the cache or touch relays.' This clarifies cost and side-effect profile, though it doesn't detail error handling or return shape (but an output schema exists).

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

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

Three short, purposeful sentences. Every sentence contributes: what, when, and side-effect profile. No redundant phrasing or filler, and the key info 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?

For a simple check tool with a complete output schema, the description fully covers intent, usage, and side effects. It also provides relevant sibling context (check_oauth_status) and is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with both 'dpop_token' and 'patron_npub' already having meaningful descriptions. The tool description does not add additional parameter semantics beyond what the schema provides, 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 opens with a specific verb and resource: 'Check whether a previously-cached dpop_token is still valid.' It clearly identifies the tool's function and distinguishes it from siblings by framing it as the npub-proof counterpart to 'check_oauth_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?

Explicit when-to-use: 'a calling agent can ask "will my next paid call accept this dpop_token?" before burning credits on a guaranteed failure.' It also names the alternative tool (check_oauth_status) and differentiates the flow, fully covering 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, so the description must carry the full transparency burden. It discloses the npub requirement and credit billing, which is useful, but it omits other behavioral traits such as whether duplicate links are prevented, what happens on failed billing, or how the graph structure is affected. The minimal disclosure leaves significant gaps.

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

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

The description is a single, front-loaded sentence with zero filler. It delivers the core action and the key prerequisite without extraneous text, making it efficient and easy to scan.

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 11 parameters, the description is very brief. It fails to mention important context such as the meaning of relation types (beyond schema), the consequences of creating a link, or any special handling of optional fields. The tool likely needs more operational context for an agent to invoke it safely and 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 description coverage is 91%, so the schema already documents all parameters well. The description reinforces thought_id_a/thought_id_b and npub but adds no new semantic meaning beyond the structured field descriptions. Baseline of 3 is appropriate when the schema does the heavy lifting.

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 'Create a relationship between two thoughts by ID' with a specific verb ('Create'), a clear resource (relationship between thoughts), and required identifiers. This distinguishes it from sibling tools like brain_update_link and brain_delete_link.

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 verb 'Create' implies this is for new relationships, and the requirement for npub indicates a prerequisite. However, it gives no explicit guidance on when to prefer this over alternatives (e.g., brain_update_link) or when not to use it, leaving usage context implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: requires npub for credit billing, automatically resolves wikilinks, leaves unresolved [[...]] literals and returns them, and advises against hand-writing brain:// URLs. This adds significant context beyond a simple 'create or update' statement.

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 well-structured with clear paragraphs for note style and linking, but it is longer than strictly necessary. The style guidance is useful but somewhat opinionated and could be condensed without losing core tool usage 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 presence of an output schema, return values need not be described. The description covers purpose, requirements, and detailed content formatting, but omits create-vs-update semantics (e.g., whether it overwrites) and lacks tool-selection guidance. It is adequate but leaves gaps for a tool with this many siblings.

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 80% schema description coverage, the baseline is 3. The description substantially enriches the meaning of the 'markdown' parameter by detailing note style, bold usage, wikilink syntax, and disambiguation via [[#thoughtId]]. It does not add to dpop_token or thought_id, but the markdown additions are meaningful and compensate partially for the missing dpop_token description.

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

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

The description states a clear action and resource: 'Create or update a note with markdown content.' This distinguishes it from siblings like brain_append_to_note (append-only) and brain_get_note (read-only), though it does not explicitly name alternatives or contrast with brain_update_thought.

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 choose this tool over alternatives such as brain_append_to_note or brain_update_thought. The extensive style and linking instructions relate to content formatting, not tool selection, leaving the agent to infer usage context 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?

No annotations are present, so the description carries the full burden. It discloses a key behavioral trait: 'Requires npub for credit billing,' indicating a paid operation. However, it does not mention other behaviors such as kind restrictions (Tags/Events rejected) or that it creates a node in the active brain.

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

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

Two concise sentences with the action front-loaded. No filler or redundant information. Every word 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 rich schema (92% coverage) and existence of an output schema, the description provides a sufficient high-level overview of the tool. It could mention the kind restriction or linking details, but those are covered by the schema; overall it is complete enough for an agent to select and invoke the tool 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 high (92%), so baseline is 3. The description summarizes some parameters ('optional type, color, label, and parent link') and highlights the required npub, but these details are already present in the schema. It adds little new semantic meaning 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 action 'Create' and the resource 'a new thought', and lists optional attributes (type, color, label, parent link). This distinguishes it from siblings like brain_create_link (creates links) and brain_update_thought (updates existing thoughts).

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 via the verb 'Create' and resource 'thought', but does not explicitly state when to use it versus alternatives like brain_create_link or brain_morph_thought. No exclusions or alternative guidance 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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that npub is required for credit billing, which hints at a billing side-effect, but it does not mention whether deletion is permanent, whether it affects associated content, or any permissions needed. The description also contradicts the input schema by claiming npub is required while the 'required' array only lists attachment_id.

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

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

The description is extremely concise: two short sentences that front-load the core action and then the key requirement. Every word adds value, with no redundancy or filler.

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

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

For a delete operation with no annotations and an output schema, the description is quite sparse. It does not explain the return value (although output schema exists, so that is mitigated), nor does it provide context about consequences, permissions, or the role of brain_id and dpop_token. Given the complexity of the parameter set and the absence of annotations, more behavioral context would be expected.

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% (npub, brain_id, attachment_id have descriptions; dpop_token lacks one). The description adds a slight clarification that npub is for credit billing, but this mostly repeats the schema's npub description. It does not add semantics for attachment_id, brain_id, or dpop_token.

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

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

The description clearly states the action ('Delete') and the resource ('an attachment'), with a specific and unambiguous verb+resource structure. It naturally distinguishes from sibling tools like brain_add_url_attachment, brain_list_attachments, and brain_get_attachment.

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, nor any mention of prerequisites beyond the npub requirement. There is no indication of ownership checks, active brain behavior, or scenarios where deletion is appropriate or forbidden.

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 critical behaviors: cascading deletion to patron redemptions, orphan references becoming no-ops with warnings, and operator-only restriction requiring proof. This is rich, specific context beyond a simple 'deletes a coupon'.

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: the first sentence states the core action, the second explains the cascade, and the third gives the access restriction. Every sentence adds value with no filler or redundancy.

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

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

For a deletion tool, the description explains the core behavior, side effects, and access control, which is sufficient for most usage. It lacks details on how to obtain dpop_token or what 'proof' entails, but since an output schema exists, return values are not required. It is nearly complete, though the dpop_token gap prevents a perfect score.

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

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

Schema coverage is 0%, so the description must explain parameters. It implicitly identifies coupon_id as the identifier of the coupon to delete (via 'deleted coupon_id'), but it does not explain the format or origin. dpop_token is completely unexplained, despite being a required parameter for operator proof. The description fails to compensate for the missing schema descriptions.

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

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

The description clearly states the action ('Delete a coupon') and specifies the resource (coupon) with a distinctive side effect ('Cascades to all patron redemptions'). This distinguishes it from other deletion tools like brain_delete_thought or brain_forget_coupon, which likely have different scopes or behaviors.

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 clear context for when to use the tool: it is RESTRICTED to operators and requires proof, and it cascades to redemptions, implying it should be used only when that effect is intended. However, it does not explicitly mention alternatives (e.g., brain_forget_coupon) or state when not to use it, so it lacks 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?

Without annotations, the description discloses the most critical behavioral traits: the deletion is permanent, cannot be undone, and requires an npub for credit billing. This covers the destructive nature and a unique billing requirement, though it does not mention side effects on related data or error behavior.

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

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

The description is two short sentences, directly stating the action, permanence, and prerequisite. No filler or redundancy beyond the emphasis on permanence.

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 and the tool's straightforward delete operation, the description covers the core purpose, the destructive consequence, and the billing prerequisite. It omits details like the optional brain_id fallback, but these are already in the schema, so the description is reasonably complete.

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

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

The schema already provides descriptions for 75% of parameters (link_id, npub, brain_id). The description only reinforces the npub billing requirement, adding little beyond the schema. It does not clarify dpop_token or the optional brain_id behavior, but the schema covers the essentials.

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 identifies the tool as deleting a link by ID, using the specific verb 'delete' and resource 'link'. It also differentiates from sibling tools like brain_delete_thought or brain_delete_attachment by explicitly targeting links.

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 implicit usage context by stating what the tool does, but it does not explicitly mention when to use this over alternatives or any exclusions. It gives no guidance about when not to use it, such as for soft deletes or when to use brain_update_link instead.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a write to a sensitive credential vault, that proof of ownership is required, and that it is free. It also notes a non-destructive effect on other fields. It does not mention reversibility or failure behavior, but the output schema likely covers return details; overall this is solid for a delete 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 concise and front-loaded with the core action. Each sentence adds value: the action, the scope guarantee, cost, and the auth/sensitivity warning. No filler or repetition of schema 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?

Given the tool's moderate complexity (3 required params, output schema present, many siblings), the description covers the essential purpose, scope, sensitivity, and prerequisite. It could add more about error cases or what happens if the field does not exist, but the output schema likely handles return semantics. Overall, it is sufficiently complete for typical 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?

The input schema provides 100% coverage, including detailed descriptions for npub, field, and dpop_token. The description adds no new parameter-level syntax or examples beyond what the schema already offers, so it stays at the baseline for good schema coverage.

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

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

The description uses a specific verb ('Remove') and resource ('single patron credential field') and further clarifies scope by noting it deletes one field without affecting others. This clearly distinguishes it from sibling tools like update (brain_update_patron_credential), bulk delete (brain_forget_credentials), or read (brain_get_patron_credential_fields).

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 conveys clear context: this tool is for deleting a single credential field while preserving other fields. It also states proof of npub ownership is required, which signals a prerequisite. However, it does not explicitly name alternatives or state when not to use it (e.g., for deleting all credentials), so it misses the higher bar of 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 provided, the description carries the burden of disclosure. It does disclose the irreversible nature ('Cannot be undone') and the billing prerequisite ('Requires npub'), which are significant. However, it omits behavioral details like the optional `confirm` parameter's audit-grade verification and the extra billable read it costs, which is a gap for a delete 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, front-loaded sentence that states the action, irreversibility, and a key precondition with no redundant words. Every phrase 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?

The output schema exists so return values are handled. The description covers the essential destructive context and billing requirement, but it omits significant nuances like the `confirm` parameter's audit-proof behavior and the cost of an extra read. For a tool with 5 parameters and no annotations, a more complete overview would help, but the core usage is clear.

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 80% (four of five parameters documented), so the schema already explains most params. The description adds only that npub is for credit billing, which is redundant with the schema's description. It does not clarify the undocumented `dpop_token` parameter or add syntax/format details, so the description adds little value beyond the schema.

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

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

The description clearly states 'Permanently delete a thought by ID', with a specific verb and resource, and clearly distinguishes from siblings like brain_create_thought and brain_update_thought. The additional warning 'Cannot be undone' reinforces the destructive 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 implies usage: it's for deleting a thought, and notes the requirement of npub for credit billing. However, it does not explicitly contrast with alternatives or state when not to use it, leaving the usage context to be inferred from the tool name and the 'permanent' warning.

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 one key behavioral trait: the need for npub for credit billing, implying a paid operation. But it does not mention whether the operation is idempotent, what happens if the person or day already exists, or any side effects beyond creation. The description is too sparse for a mutation tool.

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

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

The description is only two sentences, front-loaded with the main action and followed by the key requirement. Every word is efficient with no redundancy or 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?

The description is brief and does not explain what 'Event+Person+Day' conceptually means or what the output will be (though an output schema exists). The schema fills in parameter details, but the composite nature of the operation and its relationship to other tools (e.g., why not create separately) are not elaborated. It is minimally adequate but leaves 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 high (86%), with parameter descriptions already explaining most fields. The tool description adds 'Requires npub for credit billing,' but this duplicates the schema's explanation for npub ('Required... for credit billing'). It does not clarify parameters like date, person, or event_name beyond what the schema provides, so it adds little 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 states a clear action: 'Create an Event+Person+Day in one action.' This specifies the verb (Create) and the composite resource, distinguishing it from single-entity creation tools like brain_create_thought. However, 'Event+Person+Day' could be clearer, and it doesn't explicitly name alternatives, so it falls short of a 5.

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

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

The phrase 'in one action' implies this is for combining multiple creations, providing a basic usage context. However, there is no explicit guidance on when to use this versus creating events, persons, or days separately, nor any exclusions or alternatives. This is implied usage, not clear 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. It openly discloses the cosmetic-only nature, the coupon's persistence at the operator, re-redemption possibility, and the npub proof requirement. This is strong transparency for a simple mutation tool, though it doesn't cover potential error conditions or idempotency.

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

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

The description is three sentences with no wasted words. The primary action is front-loaded, followed by key caveats (cosmetic, free, npub proof). Every sentence contributes unique 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 simple tool, the description covers the core action, side effects, and auth requirement. The output schema is present, so return values are presumably covered. However, the parameter gaps (especially coupon_id) prevent a perfect score, as the description relies on the user's prior knowledge of 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 0%, so the description must compensate, but it only adds meaning for npub ('requires proof of npub'). It does not explain coupon_id or dpop_token, leaving two of three parameters ambiguous. This under-compensates for the lack of schema descriptions.

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

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

The description clearly states the action: 'Remove a coupon from this patron's redemption list.' The qualifier 'Cosmetic only' distinguishes it from related tools like brain_delete_coupon, preventing ambiguity about its non-destructive nature.

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 clear context by stating that the coupon still exists and can be re-redeemed, implicitly indicating this is for non-destructive removal. It also mentions the 'requires proof of npub' prerequisite. However, it does not explicitly name alternative tools, so it lacks an explicit when-not-to-use instruction.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation requires proof of npub ownership and is 'as destructive as a write', which is critical safety context. It does not detail irreversibility or rate limits, but the key behavioral trait is well communicated.

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

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

The description is three concise sentences: purpose, usage distinction, and safety note. Every sentence adds value, and the most critical information 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?

For a destructive 3-parameter tool with a rich input schema and an output schema present, the description covers purpose, usage nuance, and a safety warning. It does not explicitly differentiate from the sibling brain_delete_patron_credential, but overall it provides enough context for correct invocation.

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

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

Schema coverage is 100% with descriptive parameter details. The description adds extra meaning by clarifying how to select the correct npub (operator vs patron) and reiterates the proof requirement tied to dpop_token. This goes beyond the schema's generic npub description.

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

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

The description clearly states the tool 'Delete vaulted credentials for a specific service and npub', which is a specific verb+resource. It also distinguishes operator vs patron credential deletion, differentiating it from sibling tools like brain_delete_patron_credential.

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

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

The description explains when to use the tool by specifying that for operator credentials pass the operator's own npub, and for patron credentials pass the patron's npub. It also warns that proof of npub ownership is always required. It does not explicitly name alternatives, but the context is clear.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It adds that credit billing applies and npub is required, which is a meaningful side-effect disclosure. However, it does not mention other behaviors such as whether the operation is strictly read-only, pagination, or error cases. The billing mention provides partial 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 two short sentences: the first gives the core purpose, the second adds a key requirement. It is front-loaded and every word contributes value. No redundancy or verbose phrasing.

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 (get metadata) and the presence of a detailed schema (75% parameter coverage) and an output schema, the brief description adequately covers the essential context. It mentions the billing prerequisite and the action. It could be slightly more explicit about the distinction from content retrieval, but the name and sibling context make this inferable.

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 new parameter semantics beyond what the schema already provides. Schema description coverage is 75% (three of four parameters are documented in the schema), and the only parameter it hints at, npub, is already described as required for credit billing. The description does not clarify the undocumented dpop_token, and brain_id and attachment_id are already well-described in the schema.

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

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

The description states 'Get metadata about an attachment' with a specific verb and resource, clearly distinguishing it from sibling brain_get_attachment_content, which likely retrieves content. This gives an immediate, unambiguous 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 notes 'Requires npub for credit billing,' implying a prerequisite and cost. However, it does not explicitly state when to use this tool versus alternatives like brain_get_attachment_content or brain_list_attachments. Usage context is implied but not made explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions the npub requirement for credit billing, which is a useful behavioral trait, but omits other important aspects such as side effects (e.g., whether save_to_path writes to disk), return format, or potential size limitations. This is insufficient for a tool that retrieves binary 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 extremely concise: two sentences, first states the core purpose, second adds the billing requirement. There is zero waste, and the key action 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?

The tool is relatively simple, and the schema covers most parameters. However, the description lacks important context about how the binary content is returned (e.g., base64, file download) and does not clarify the relationship to the sibling tool brain_get_attachment. It also doesn't explain the behavior of the optional save_to_path parameter, despite that being a notable feature.

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

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

The input schema covers 80% of parameters with descriptions, so the baseline is 3. The description's mention of 'Requires npub' adds no new information because the schema already describes npub as required for billing. It does not clarify the purpose of dpop_token or elaborate on save_to_path behavior 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 retrieves the binary content of an attachment, which is a specific verb+resource action. While it implicitly distinguishes from the sibling tool 'brain_get_attachment' via the modifier 'binary', it does not explicitly differentiate them, leaving a small 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?

No guidance is provided on when to use this tool versus alternatives like brain_get_attachment or brain_list_attachments. The only additional information is the npub requirement for billing, which is a prerequisite rather than usage context, so the agent gets no direction on selecting 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?

With no annotations provided, the description carries the full burden. It adds one useful behavioral detail (npub required for credit billing) but fails to disclose aspects like whether the operation is read-only, what happens without npub, or any rate limits. The description is too sparse to give the agent confidence about side effects or requirements beyond the billing note.

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 only two sentences, with the core purpose first and the billing requirement second. Every word earns its place, and there is no redundancy or 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?

The tool is a simple get-by-ID operation with an output schema present, so return values are likely covered by the schema. The description adds the billing context, but lacks guidance on when to use it versus sibling tools, and the npub requirement is stated without explaining whether it is mandatory at the API level despite not being listed as a required schema property. This leaves some ambiguity for a low-complexity 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 67% (npub and brain_id have descriptions; dpop_token does not). The description adds context that npub is required for credit billing, which supplements the schema's note on npub. However, brain_id is described only as 'The ID of the brain' with no additional semantic value, and dpop_token remains unexplained. This is adequate but not exceptional.

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: 'Get details about a specific brain.' The verb 'get' and resource 'specific brain' distinguish it from sibling tools like brain_list_brains (which lists brains) and brain_get_brain_stats (which gets stats). However, it does not explicitly mention that it retrieves by brain_id, though the schema covers that.

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 prerequisite ('Requires npub for credit billing') but does not state when to use this tool vs alternatives or any exclusions. It implies use when you need details of a single brain, but there is no explicit guidance about preferring this over brain_list_brains or other getters.

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 disclosing behavioral traits. It does reveal the credit billing requirement, which is a notable operational cost. However, it doesn't clarify whether the operation is read-only, whether credits are actually deducted, or what side effects might occur, leaving some ambiguity.

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

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

The description is exceptionally concise, consisting of two short sentences that state the core purpose and the key prerequisite. No fluff or redundancy.

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

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

The output schema likely covers return values, so the description needn't explain that. However, the tool involves credit billing, which presents financial implications. The description only hints at this via the npub requirement. For a tool with billing side effects and many siblings, the description would benefit from more context, such as typical use cases or confirmation that it's a read-only operation.

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

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

The schema already documents npub and brain_id with descriptions, so the description adds marginal value here. The mention that npub is required for credit billing reinforces the schema's description of npub, but the dpop_token parameter remains completely unexplained, and the description doesn't clarify how brain_id interacts with the active brain beyond what the schema states.

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 ('Get statistics') and the resource ('brain'), making it distinct from sibling tools like brain_get_brain or brain_get_attachment. However, it doesn't specify exactly which statistics are returned, which would add further 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?

The description only notes the npub requirement, which is a prerequisite rather than guidance on when to use this tool versus alternatives. No contextual usage scenarios or exclusions are provided, leaving the agent without clear decision 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?

With no annotations, the description carries the burden of behavioral disclosure. It adds the important fact that using the tool requires npub for credit billing, indicating a billing-related side effect. However, it does not explicitly state whether the operation is read-only or whether credits are consumed, leaving some transparency 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, concise sentence that immediately states the tool's purpose and the key usage requirement. There is no wasted or redundant wording.

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

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

Given that an output schema exists, return values are covered. The description sufficiently conveys the tool's purpose and the billing precondition. A minor gap is the lack of clarification about optional parameters like brain_id, but this is already in the schema. Overall, it is a well-rounded description for a simple getter.

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%, so the schema already documents most parameters. The description's mention of npub simply repeats what the schema says, adding no new meaning. It does not elaborate on link_id or brain_id 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's function: 'Get details about a specific link.' This is a specific verb+resource combination, and the sibling tools include brain_create_link, brain_update_link, and brain_delete_link, so the purpose is distinct and unambiguous.

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

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

The description provides a precondition ('Requires npub for credit billing') which is useful context for when the tool can be used. However, it does not explicitly compare to alternatives or state when not to use this tool, so the guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and excels: it discloses credit billing via npub, uncached latency behavior, inclusion of operation codes (CREATED/DELETED/etc.) with old→new values and timestamps, and clarifies the subtle semantics of userId distinguishing desktop vs API activity. No contradictions.

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 well-structured with a strong opening definition, bulleted use cases, and a warning sub-section. Every sentence adds necessary context; the length is justified by the tool's complexity and the need to distinguish from siblings.

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 and the existence of an output schema, the description covers all key context: billing, uncached nature, operation types, use cases, peer discovery, and userId semantics. It fully addresses when and why to use this over alternatives.

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 baseline is 3, but the description adds value beyond the schema: it explains how to use mod_types (e.g., [102] for deletes) with specific operation codes, and gives context for start_time in read-after-write verification. The npub requirement for billing is also clarified beyond the schema's default.

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 identifies the tool as the brain's authoritative, uncached change-log, with a specific verb+resource+scope. It distinguishes itself from siblings by explicitly naming get_thought_graph and search as cached alternatives that are stale for recent writes.

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 explicit when-to-use guidance: confirming writes after mutations (with a start_time strategy) and discovering recent/peer activity. It also mentions alternative tool behavior (heavy mutating tools with confirm=True) and contrasts with cached graph/search use cases.

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

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

With no annotations, the description carries the full burden. It discloses return behavior (fields or empty profile) and the lack of proof requirements, which is useful context. It does not cover edge cases like invalid npub or rate limits, but given it's a simple read, transparency is good.

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

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

The description is two sentences, front-loaded with the core purpose, and lists specific fields. No redundant information is present.

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

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

The description covers purpose, usage context, and return behavior, and an output schema exists. However, it doesn't clarify behavior for an empty or invalid npub parameter, which is a minor gap given the schema marks it optional with a default.

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 lone parameter 'npub' has no schema description (0% coverage), so the description must compensate. It mentions 'npub' in the first sentence, indicating it's the public key, but lacks format details or default behavior. The description partially clarifies the parameter's role.

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

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

The description clearly states the tool reads a public Nostr profile, specifying it's NIP-01 kind-0 metadata. It also lists the exact fields returned, distinguishing it from sibling write tools like brain_publish_nostr_profile.

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

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

The description notes the tool is 'Free, no proof' and that the data is already public, implying it can be used without authentication. However, it does not explicitly name alternatives or state when not to use it, leaving usage guidance implied.

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 must carry the full burden of behavioral disclosure. It explains the operation (compute a proof from a snapshot) but does not disclose whether it is read-only, any prerequisites (e.g., existing notarization), error conditions, or what the proof can be used for. It implies a safe computation but lacks explicit guarantees.

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-structured sentence that leads with the verb and object, immediately conveying the tool's purpose without any filler or redundant information. It earns its place with every word.

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 (two required parameters, no nested objects, and an output schema present), the description adequately covers what the tool does. However, it could be more complete by explicitly stating when to use it relative to sibling proof-related tools, but this is not a critical gap for a straightforward proof generation 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?

Since schema coverage is 100% and both parameters have clear descriptions (npub as Nostr public key, notarization_id as record ID), the description adds minimal semantic value beyond linking the two parameters: the proof is for a specific patron and a specific notarization. No additional format or constraint details are provided.

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

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

The description clearly states the tool generates a Merkle inclusion proof that a patron's balance was included in a Bitcoin-notarized snapshot. The verb 'generate' and the specific resource 'Merkle inclusion proof' distinguish it from related tools like brain_notarize_ledger (creates the snapshot) and brain_check_proof_status (checks 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?

The description implies the tool is used when one needs a proof of inclusion for a patron's balance in a notarized snapshot, but it does not explicitly state when to use it over alternatives such as brain_check_proof_status or brain_receive_npub_proof. No exclusions or comparable scenarios are mentioned.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that npub is required for credit billing, which is a valuable behavioral note. But it does not mention potential side effects, whether it is read-only, or what happens if required inputs are 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?

The description is two sentences with no wasted words. It leads with the primary action and follows with the key requirement, making it easy to parse quickly.

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

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

Given that an output schema exists and this is a simple getter, the description is nearly complete. It covers the main purpose and billing constraint. The only gap is the lack of clarification on how format and brain_id interact, but these are adequately described in the 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 80%, so the schema already documents most parameters. The description adds that npub is needed for credit billing, which enriches the schema's note, but does not clarify ambiguous fields like dpop_token. Overall, it provides marginal added value beyond the schema.

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

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

The description 'Get the note content for a thought' uses a specific verb and resource, clearly identifying what the tool does. It does not explicitly distinguish from siblings, but 'note content' narrows the scope versus other thought-related 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?

The description implies usage by stating 'Requires npub for credit billing,' which signals a prerequisite. However, it provides no guidance on when to use this tool versus alternatives like brain_get_thought, nor does it mention exclusions or conditions.

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

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

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only reporting operation ('Report', 'Shows') with no mention of side effects or mutations. The inclusion of 'Free' adds useful behavioral context about pricing. It does not disclose permissions, but for a non-mutating status check, the lack of explicit side-effect disclosure is acceptable given the strong read-only implication.

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 four short sentences, each earning its place: purpose, details, alternative, and cost. It is front-loaded with the main action and avoids fluff or repetition of the tool name.

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

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

Given the tool's simplicity (no params, output schema present, no annotations), the description covers all essential aspects: what it does, what information it provides, when to use an alternative, and cost. The output schema defines the return structure, so no return-value explanation is needed. It is fully adequate for an agent to select and invoke this tool correctly.

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

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

The tool has zero parameters, so the baseline per the rubric is 4. The description does not need to explain any parameters, and the empty input schema is self-explanatory.

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 opens with 'Report this operator's configuration readiness,' a specific verb+resource statement that clearly identifies the tool's function. It then elaborates that it shows which operator settings are configured, which are missing, and how to deliver each missing value, distinguishing it from the patron-level sibling tool via an explicit 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 explicitly says 'For patron-level credential status, use get_patron_onboarding_status instead,' providing a clear alternative and when-not-to-use condition. The main use case is obvious from the purpose statement, and the 'Free' note adds context about cost, making usage conditions sufficiently clear.

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

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

With no annotations, the description carries full burden. It discloses that values are never exposed, that timestamps may be null for older vaulted secrets, that the tool is free, and that proof of npub ownership is required due to the sensitivity of the field list. This is rich, useful behavioral context.

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

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

The description is concise and well-structured. It front-loads the core purpose in the first line, followed by two short paragraphs with valuable details (timestamp behavior, sensitivity, auth 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?

The description is complete for its complexity. It explains what is returned (field names, timestamps), what is never returned (values), why auth is needed, and the cost (free). With an output schema present, there is no need to describe return format in detail.

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 parameters are already well-documented in the schema. The description adds no additional parameter-specific semantics beyond what the schema provides (e.g., npub and dpop_token details are fully explained in the schema). 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 opens with 'List stored patron credential field names (not values)', using a specific verb and resource. It clearly distinguishes itself from siblings like brain_update_patron_credential by focusing on read-only field name listing and explicitly excluding value exposure.

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 states an explicit use case: 'use this to verify which fields are configured and how old each one is.' It also implies when not to use it by noting 'Values are never exposed'. However, it does not name alternative tools for value retrieval, so it falls slightly short of a 5.

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

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

With no annotations, the description carries the full burden of disclosing behavioral traits. It discloses that the tool is free, requires proof of npub ownership (D PoP token), and explains why (credential presence is sensitive). It implies read-only behavior via 'Report' and describes how different service types are handled. It could mention error conditions or side effects, but the provided details are strong.

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

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

The description is three sentences with no waste. It front-loads the core purpose, then adds necessary context about service types, cost, and authorization. Every sentence earns its place, making it appropriately concise and well-structured.

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

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

The tool has an output schema, so return format doesn't need to be in the description. The description covers purpose, service-specific behavior, cost, and auth requirements, making it fairly complete for a read-only status tool. It doesn't mention failure scenarios or edge cases, but given the simplicity and output schema, the information provided is sufficient.

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 extra meaning by explaining why dpop_token is required ('Proof of npub ownership is required') and why the data is sensitive, which gives the agent deeper understanding of the parameters beyond their schema definitions. This justifies a score above baseline.

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: 'Report a patron's credential readiness for this operator.' It uses a specific verb ('Report') and names a distinct resource (patron credential readiness), and it differentiates from sibling tools by specifying patron-level vs. operator-level status and service-specific behavior (set-once vs. OAuth2).

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 clear context on when to use the tool: to report credential readiness for a patron, with distinctions between service types. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide an agent. A small gap is the lack of explicit comparison to similar tools like brain_get_operator_onboarding_status.

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 weight. It openly discloses a significant side effect: self-initializing a scaffold with all tools at 0 sats when no model exists. It also reveals a constraint ('No economic data from code'). This is exceptional transparency for a read-like operation, exceeding typical expectations.

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

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

The description is three concise sentences, front-loaded with the primary action. It efficiently packs the core purpose, a cost signal ('Free'), and two important behavioral details without any filler. 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 zero-parameter schema and presence of an output schema, the description covers the essential action, side effects, and constraints. It could have added a note about when to prefer this over brain_check_price or brain_set_pricing_model, but that's not critical for a simple getter. Overall, it's sufficiently complete for an agent to 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?

There are zero parameters, so schema coverage is 100% and no parameter explanations are needed. The description adds context about the implicit operator scope ('for this operator') and self-initialization behavior, which enriches understanding beyond the empty schema. Baseline 4 is appropriate.

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

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

The description clearly states 'Get the active pricing model for this operator' with a specific verb and resource. It distinguishes from siblings like brain_set_pricing_model and brain_reset_pricing_model through the verb, though it doesn't explicitly name alternatives. The extra 'Free' is ambiguous but doesn't obscure the 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 implies it is used to retrieve the pricing model but provides no explicit guidance on when to use this over alternatives like brain_check_price or brain_set_pricing_model. It does mention a behavioral condition ('If no model exists') which hints at a scenario, but not a clear call-to-action.

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

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

No annotations are provided, so the description carries the full burden. It discloses the credit billing requirement, and 'get' implies a read-only operation. However, it lacks details on potential costs, pagination, 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?

Two short sentences, front-loaded with the action, contain no unnecessary 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?

The description is adequate for a simple getter with an output schema, but it lacks context regarding when to use this tool compared to siblings and omits behavioral caveats beyond billing.

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 high (67%) and already describes npub and brain_id. The description merely repeats the npub requirement without adding new meaning, and dpop_token remains undocumented.

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

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

The description 'Get all tags in a brain' uses a specific verb (get), resource (tags), and scope (brain), making it clear and distinct from sibling tools like brain_get_types or brain_get_brain.

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 vs alternatives. The only extra information is the billing prerequisite (npub), which is a constraint rather than a usage recommendation.

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 for behavioral disclosure. It only repeats the npub billing requirement already in the schema, and does not mention read-only nature, return behavior, 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?

The description is a single sentence that front-loads the purpose and includes only the essential billing note. It is concise without 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?

Despite having an output schema, the description lacks sufficient behavioral and usage context. It does not explain when to use this tool, how billing works, or what happens with missing optional parameters, leaving the agent with significant ambiguity.

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%, leaving dpop_token undocumented. The description adds no new meaning for any parameter beyond what the schema already states, such as npub's billing purpose or brain_id's default behavior.

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 retrieves details about a specific thought, using a specific verb and resource. It does not explicitly differentiate from similar siblings like brain_get_thought_by_name, but the purpose is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternative retrieval tools. The mention of npub for credit billing is a prerequisite, not a usage context, so it offers minimal help 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?

No annotations exist, so the description carries full burden. It discloses the vendor index's incompleteness (with upstream issue link), explains false-negative behavior, and mentions billing requirements—valuable context 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?

Two tight paragraphs: one-line purpose, then a clearly marked warning. Every sentence earns its place—no fluff, critical caveat front-loaded in a dedicated section.

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 pitfalls (authoritativeness, credit billing, verification paths) and provides complete guidance for a safe usage. No gaps.

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

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

Schema coverage is 75% and the description adds meaning for npub ('for credit billing') and clarifies name_exact ('case-sensitive' in schema, exact match in description). It does not add detail for brain_id or dpop_token, but schema likely covers those sufficiently.

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 specific verb and resource: 'Exact name lookup — returns the first thought matching the name exactly.' It clearly distinguishes this tool from siblings like brain_search_thoughts (fuzzy search) and brain_get_thought (by ID).

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

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

Provides explicit when-not-to-trust: a miss is not proof of absence, and names alternative verification methods (get_thought, graph traversal) before creating duplicates. Also notes the required npub for credit billing.

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 fully discloses its non-authoritative nature, cache lag hours-to-days, that it reflects creates but NOT updates/deletes, and that it can return stale or deleted thoughts. This exceeds typical transparency and directly addresses the most important behavioral trait an agent needs to know.

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 compact and front-loaded with the purpose, followed by the critical warning and usage guidance. Every sentence adds value, with no fluff. The use of the warning symbol and clear formatting aids readability.

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 (cached layer, mutation caveats) and no annotations, the description is highly complete. It covers the key caveats, provides an upstream issue link, and clarifies when to use an alternative. Output schema exists, so return value details are not needed. This is a model 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?

Schema description coverage is 80%, so the schema already explains most parameters. The description adds nothing about individual parameters beyond the npub requirement for billing, which is also in the schema. It does not compensate for the one undocumented parameter (dpop_token), but since most are covered, the 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 'Get a thought's full connection graph' with a specific verb and resource. It distinguishes this from related tools by contrasting it with get_thought for verifying writes, and the 'full' qualifier implies the non-paginated variant. Sibling differentiation is implicit through the explicit warning against using it for recent writes and the reference to get_thought as authoritative.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Use this for fast traversal of established structure and for finding older thought IDs. Do NOT use it to verify a recent write — confirm mutations by ID with get_thought.' This names the alternative tool and the exact context where this tool is appropriate, which is exceptional.

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

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

The description reveals critical behavioral traits: the cached layer lags writes by hours-to-days, does not reflect updates/deletes, and requires npub for credit billing. With no annotations provided, this disclosure is essential and well-handled.

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

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

The description is concise and well-structured: a one-sentence purpose, a one-sentence requirement, then a clear warning block. Every sentence provides 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 output schema exists and the input schema has high coverage, the description covers all necessary context: purpose, usage constraints, data freshness limitations, and billing requirement. It is fully sufficient for an agent to select and invoke the tool 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 88%, so parameters are well-documented in the schema. The description adds minimal parameter-specific meaning beyond noting npub is required and that pagination is cursor-based, which is already implied by the schema fields.

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 performs 'Cursor-based paginated traversal of a thought's connections', which is specific and distinguishes it from non-paginated get_thought_graph. It also clarifies it is for traversal/ID discovery, not authoritative verification.

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

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

Explicitly states when to use ('traversal/ID discovery') and when not to ('never as read-after-write verification'), with a clear alternative ('confirm mutations by ID with get_thought'). This provides strong guidance beyond the schema.

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 disclosure burden. It explicitly discloses that the operation requires npub and incurs credit billing, which is a significant behavioral trait. It does not detail other aspects like output format, but the 'List' verb implies a read-only action and output schema covers return values.

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

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

The description is two focused sentences with no fluff. It front-loads the core purpose and adds the critical billing requirement efficiently.

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

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

The description covers the essential action and a key prerequisite, and output schema handles return values. However, it lacks guidance on alternatives, does not define what 'thought types' are, and fails to address the undocumented dpop_token parameter, leaving some gaps for a complete understanding.

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

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

The description only repeats the npub requirement from the schema and does not add meaning for brain_id or dpop_token. With 67% schema description coverage, the dpop_token parameter remains undocumented in both the schema and the description, leaving a gap.

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

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

The description clearly states a specific verb ('List') and resource ('all thought types defined in the brain'), distinguishing this tool from siblings by focusing on 'thought types' as a unique concept. The scope ('all') is unambiguous.

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

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

The description provides a prerequisite (npub required for credit billing) but does not explicitly state when to use this tool over alternatives like brain_get_tags or brain_list_constraint_types. Usage is implied rather than clearly guided.

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

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

No annotations are provided, so the description carries the full burden. It discloses that an npub is required for credit billing, which is a meaningful cost-related behavioral trait. However, it does not describe other aspects such as whether the operation is read-only, potential side effects, or output format, though the output schema covers the latter.

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

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

The description is two sentences and every word adds value: the first states the core action, the second states a critical requirement. It is front-loaded with the 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?

For a simple list operation with an output schema, this description provides adequate context. It states the primary purpose and the credit billing requirement, which is the key non-obvious aspect. The optional brain_id and dpop_token are documented in the schema, so their absence from the description is not a significant gap.

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

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

The schema already documents 75% of parameters, including npub, brain_id, and thought_id. The description reinforces that npub is required but adds no new parameter semantics beyond the schema. With high schema coverage, a baseline of 3 is appropriate.

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

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

The description uses a specific verb 'List' and a clear resource 'attachments for a thought', which distinguishes it from sibling tools like brain_get_attachment (singular retrieval) and brain_add_file_attachment (adding). The scope is explicit and unambiguous.

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

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

The description clearly states the context for use: listing all attachments for a thought. While it doesn't explicitly name alternatives, the operation's purpose is unambiguous, and the npub requirement provides practical usage context. It lacks explicit exclusions or when-not-to-use guidance, but this is a simple listing operation.

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 the action without mentioning any side effects, authentication requirements, rate limits, or return format. It fails to convey that this is likely a read-only operation or that the npub parameter is tied to credit billing, which is only revealed in 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?

The description is a single concise sentence that is front-loaded with the primary verb and object. It avoids unnecessary words, which is good for conciseness, though it may be too sparse to provide full context. No structural issues.

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

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

Despite having an output schema, the description lacks sufficient context for a tool with two parameters and no annotations. It does not mention the billing requirement, the purpose of the parameters, or any behavioral details. For a tool that lists brains, the description is minimal but functional; however, the lack of additional context makes it incomplete for agents that need to know how to invoke it correctly.

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

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

The description adds no parameter information beyond the input schema. Schema description coverage is only 50% (npub has a description, dpop_token does not), so the description should compensate, but it does not. The dpop_token parameter remains completely unexplained, and the tool description does not clarify the billing context of npub.

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 available brains.' clearly states the action (list) and the resource (brains), making it easy to understand the tool's basic function. However, it does not distinguish this from sibling tools like brain_get_brain or specify the scope of 'available brains' (e.g., user's own vs all accessible), so it lacks sibling 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?

There is no guidance on when to use this tool versus alternatives. With many sibling tools for brain-related operations, the description gives no indication of prerequisites, context, or exclusions, leaving the agent without sufficient information to choose it confidently.

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 explicitly discloses 'Free, no side effects,' explains the two sources of identity (ToolIdentity-seeded and @paid_tool recorded UUIDs), and describes the unregistered/deploy-drift detection behavior including the mcp_name-change-vs-tool_id-stability design point. Very transparent about return semantics.

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

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

Slightly long with some redundancy — the unregistered/deploy-drift concept is explained twice (once for @paid_tool UUIDs and again for wire-surface diff). Could be tightened, but every sentence adds meaningful context and the key points are front-loaded in the first line.

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

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

Output schema exists, so return format doesn't need explanation. The description thoroughly covers sourcing, edge cases (missing registry UUIDs, wire-only tools), the canonical-UUID design intent, and lack of side effects. Complete for a zero-parameter introspection tool.

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

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

The schema has 0 parameters with 100% coverage, so baseline is 4 per rubric. Nothing needed here; the description correctly focuses on behavior rather than inventing parameter semantics. No issue.

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

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

Clear specific verb+resource: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' Unambiguous scope. It's a list/metadata introspection tool clearly distinct from siblings like brain_list_brains, brain_list_attachments, etc. which all return domain resources — this one describes registry identity mapping, functionally unique.

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 names the consumer ('any client (Studio, agents, FE) that needs to know how this MCP identifies its tools') and gives concrete use context (Reconcile UUID-join against pricing model, no name-based derivation). Even mentions issue numbers (#174, #175). Strong behavioral guidance about when to reach for 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?

No annotations are provided, so the description carries the transparency burden. It discloses the return contents (type, category, description, parameter specs) and adds a notable cost detail ('Free — no credits required'). It does not mention side effects or permissions, but for a read-only listing this is adequate.

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

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

The description is two short paragraphs, front-loaded with the main action, and contains no filler. Every sentence adds value: purpose, return details, and cost note.

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 list tool with an output schema present, the description is complete. It specifies what the output contains and provides the context of pricing pipeline usage. No additional behavioral or operational details are necessary.

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

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

The tool has zero parameters, so the input schema is trivially covered. Per rubric, the baseline is 4. The description correctly focuses on the output rather than parameters, and no further clarification is needed.

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

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

The description uses a specific verb ('List') and identifies the resource ('constraint types') while clarifying the scope ('used in a pricing pipeline'). It is distinct from sibling tools like brain_list_brains or brain_list_coupons by focusing on constraint schemas.

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

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

The description clearly indicates this is for listing constraints relevant to a pricing pipeline, which gives context for when to use it. However, it does not explicitly mention alternatives or exclusions, though the specificity of 'pricing pipeline' helps differentiate.

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 behavioral burden. It discloses the newest-first ordering, that each row includes the 'times_redeemed' counter, and the operator/proof restriction. It adds context about how the Studio renders a progress bar from this counter. It stops short of explicitly stating read-only semantics or pagination behavior, but for a list operation the key behavioral traits are covered.

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

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

The description is two sentences long, front-loaded with the primary action ('List every coupon this operator has minted'), followed by a useful field detail and a clear restriction. Every sentence earns its place with 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?

The tool is simple (one optional parameter, no nested objects) and has an output schema, which reduces the burden on the description. However, the description leaves the 'dpop_token' parameter unexplained and does not differentiate from the sibling 'brain_list_my_coupons'. It provides adequate context for the core operation but misses these important points.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter 'dpop_token'. The description mentions 'requires proof' but never explains that this parameter is the proof token, nor how to obtain or use it. It adds no direct meaning to the parameter, leaving the agent without essential guidance for a required-looking auth token.

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 specific verb and resource: 'List every coupon this operator has minted (newest first).' It clearly identifies the scope (operator-minted coupons) and ordering (newest first). However, it does not explicitly distinguish itself from the sibling tool 'brain_list_my_coupons', which could be seen as overlapping.

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 includes a usage restriction: 'RESTRICTED to operator — requires proof.' This tells the agent when the tool can be used (by operators with proof) but does not provide explicit guidance on when to use this tool versus alternatives like 'brain_list_my_coupons' or other list tools. No exclusions or alternative pointers are given.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that both active and exhausted redemptions are returned, enumerates possible statuses, and notes that it is free and requires npub proof. This adds meaningful context, though it does not explicitly confirm read-only behavior, which is strongly implied by the verb 'list'.

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

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

Two sentences where every word earns its place: the first states the purpose with scope, the second packs return statuses and cost/auth requirements with zero filler.

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

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

For a simple list tool with two parameters and an output schema, the description covers the what, scope, status values, cost, and authentication. It omits details on dpop_token and explicit alternative guidance, but these are minor gaps given the low complexity.

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

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

The input schema has 0% description coverage for parameters. The description mentions npub in the context of proof, offering some hint of its role, but it does not explain dpop_token at all. This fails to adequately compensate for the schema's silence, especially for the optional parameter.

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

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

Clearly states the action: list redeemed coupons for a specific patron on a specific operator. The patron-specific scope distinguishes it from sibling brain_list_coupons, which likely lists all 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?

Provides clear context that this tool is for viewing a patron's redeemed coupons, implying when it should be used. However, it does not explicitly mention alternatives or when not to use it, though the patron-scoped wording effectively separates it from broader coupon-listing 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 must carry the full burden of behavioral disclosure. It only says 'List recent Bitcoin notarization records,' which implies a read-only operation but gives no details on ordering, time window, side effects, or requirements. It does not add meaningful context beyond what the tool's name and schema already suggest.

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, tightly worded sentence that immediately states the action and object. There is no fluff or repetitive phrasing. It is appropriately sized for a simple list operation and front-loads the key verb.

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 is relatively simple, with an output schema covering return values and full schema descriptions for parameters. However, the description lacks usage guidance relative to sibling tools and does not explain what 'recent' means in terms of sorting or time range. While it is adequate for basic invocation, it could be more complete by mentioning alternatives or clarifying behavior, so it earns a mid-range score.

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 both parameters (limit and status) are already well documented in the schema. The description does not add any new meaning about parameters; it merely uses 'recent' informally, which could relate to limit but is not explicitly connected. Per the rubric, this is a baseline 3 because the schema does the heavy lifting.

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 'list' and resource 'Bitcoin notarization records,' clearly distinguishing it from sibling tools like brain_get_notarization_proof (gets a specific proof) and brain_notarize_ledger (creates a notarization). The qualifier 'recent' adds some context about the scope. It is a clear, direct statement of the tool's function.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that brain_get_notarization_proof should be used for a single record, nor does it indicate any exclusions or prerequisites. The only implicit usage is the verb 'list,' which is not enough to help an agent choose between this and related notarization 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 fully disclose behavioral traits. It only states 'Create a new operator-owned discount coupon' without mentioning validation rules (e.g., name uniqueness), side effects, or authorization requirements. The operator-owned qualifier hints at scope but does not explain implications.

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

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

The description is a single sentence that immediately states the action ('Create') and the object ('discount coupon'), with no unnecessary words. It is well-structured and front-loaded.

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

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

For a create operation with 7 parameters and no annotations, the description is too sparse. It does not explain what happens on duplicate names, date validation, or ownership constraints. The output schema exists but the description does not set expectations about return values or errors.

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

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

Schema description coverage is 86%, meaning nearly all parameters are already documented in the schema. The description adds no additional parameter context, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Create' and identifies the resource as a 'discount coupon' with the qualifier 'operator-owned,' clearly distinguishing it from sibling tools like brain_update_coupon, brain_delete_coupon, and brain_redeem_coupon.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or related tools like brain_update_coupon for modifying existing coupons. Usage is only implied by the verb 'Create.'

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 critical traits: atomicity, replacement semantics (old parent link deleted, not added), the requirement for npub for billing, and the extra billed read when confirm=True. These are substantive details beyond the schema fields.

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

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

The description is three sentences with no redundancy. It front-loads the purpose, then delivers the most important behavioral caveat (replacement), and ends with a practical pointer to the alternative tool. 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?

For a mutation tool with 7 parameters and no annotations, the description covers the essential context: what the operation does, how it behaves (atomic, destructive to old parent link), authentication/billing requirements, and a pointer to alternatives. The presence of an output schema means return values need not be explained, and the description is sufficiently complete for an agent to select and invoke the tool 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 86%, so the baseline is 3. The description adds little parameter-specific meaning beyond the schema; the only addition is the mention of npub for billing, but that is already in the schema. The replacement semantics for new_parent_id are also already described in the schema ('replaces all current parents'). Thus the description does not significantly enhance 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?

The description opens with 'Atomically reparent and/or retype a thought in one operation,' which uses specific verbs and identifies the resource (a thought) and the operation (reparent/retype). It distinguishes itself from sibling tools by explicitly referencing update_thought as the alternative for setting name/label, clarifying its unique 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 provides clear when-to-use guidance by stating the operation's specificity (reparent/retype in one atomic call) and explicitly directs users to update_thought for setting name/label, including the note that update_thought now accepts new_parent_id. This gives an explicit alternative and exclusion criterion.

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 and discloses several behavioral traits: operator-only access, background execution, time expectation, and cost. It goes beyond the tool name by explaining the Bitcoin/OpenTimestamps submission and the 'free' aspect, though it could additionally mention idempotency 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?

The description is extremely concise, leading with the core action then adding only highly relevant constraints (operator, latency, cost). Every sentence earns its place with no redundant phrases or filler, making it efficiently 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?

The tool is a simple, no-parameter background operation. The description covers its purpose, operational context (operator-only, background), timing (1-6 hours), and cost (free), which is sufficient for an agent to decide when and how to invoke it. With an output schema present, return values need not be described.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly implies no input is needed, and the schema coverage is vacuously complete. There is no additional parameter information 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?

The description uses a specific verb ('Build a Merkle tree... and submit the root') and clear resource ('all patron balances'), directly stating the tool's action. It clearly distinguishes from sibling tools that retrieve proofs or list notarizations, making its unique role unambiguous.

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

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

The description provides clear context for use: it is an 'Operator-only background task' with a noted 1-6 hour confirmation delay and zero cost. While it doesn't explicitly mention alternatives or when-not-to-use, the context is strong enough for an agent to recognize this is a special maintenance action, not a routine query.

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