personalbrain-mcp

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

No annotations are provided, so the description must fully disclose behavior. It states the tool is free and requires authentication, but does not explicitly clarify that it is a read-only operation (no side effects). While it implies a read by generating a statement, explicit mention of non-mutating behavior would improve transparency.

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

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

The description is concise, with three sentences covering purpose, contents, and key constraints. It is front-loaded with the main action and structured logically, with no superfluous 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 and only three parameters, the description covers the essential aspects: what the tool returns, authentication, and cost. It could be slightly more complete by explicitly stating that it is a read-only operation, but overall it provides sufficient 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 descriptions for all three parameters. The description adds context beyond the schema: it links dpop_token to 'proof of npub ownership' and explains the purpose of npub as the patron's Nostr public key. This extra context helps the agent select appropriate parameter values.

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

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

The description clearly states the tool generates a patron's account statement and lists the specific data included (purchase history, credit tranches, usage breakdown, daily logs). It also explicitly distinguishes from the operator's Authority tax balance, 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 provides key usage context: it's free, requires proof of npub ownership (dpop_token), and is intended for the patron's own account statement. It does not explicitly contrast with sibling tools like brain_check_balance or brain_purchase_credits, but the clarity of purpose and preconditions is sufficient for an agent to decide when to invoke it.

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

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

No annotations provided, so the description carries the burden. It discloses the cost (1 api_sat), verification step (`debit_or_deny`), and output components, providing good transparency beyond basic purpose.

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

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

The description is two concise sentences with no wasted words. It front-loads the purpose and packs key details (output format, cost, verification) 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?

Given the presence of an output schema and high schema coverage, the description is complete. It covers cost, verification, output structure, and relationship to sibling tool, leaving no gaps for an infographic 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?

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no extra parameter semantics beyond mentioning similarity to `account_statement`, which is not parameter-specific.

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 visual SVG infographic of an account statement, distinguishing it from the sibling `brain_account_statement` which likely returns raw data.

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

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

The description mentions cost and verification but does not explicitly state when to use this tool over alternatives or provide exclusion criteria.

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

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

No annotations provided, so description must disclose behavioral traits. It only mentions the action and a requirement. Missing details: what happens on invalid file_path, whether attachments overwrite, size limits, or effects on thought. For a mutating tool, this is insufficient.

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

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

Two concise sentences: one for purpose, one for requirement. Front-loaded with main action. No unnecessary words, though some useful details are omitted.

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 (not shown), the description lacks critical context: supported file types, size limits, behavior when thought_id is missing, and distinction from URL attachment. For a tool with 6 parameters and significant side effects, it is incomplete.

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

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

Schema description coverage is 83%, so most parameters are already documented in the schema. The description adds no extra parameter meaning beyond 'Requires npub,' which is already in 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?

Description clearly states the action: 'Add a file attachment to a thought.' The verb 'add' and resource 'file attachment' are specific. It distinguishes from sibling 'brain_add_url_attachment' by mentioning 'file', but does not explicitly contrast them.

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

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

No guidance on when to use this tool vs alternatives like brain_add_url_attachment or brain_delete_attachment. The only usage hint is 'Requires npub for credit billing,' which is a prerequisite, not a usage scenario.

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 behavioral fact ('Requires npub for credit billing'), which is useful. However, it does not disclose idempotency, side effects, or whether the thought must exist. This is adequate but minimal.

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

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

The description is a single sentence that states the purpose immediately and includes a critical prerequisite. 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 an output schema exists and the tool is simple, the description covers the core purpose and a key constraint (npub for billing). It does not mention thought existence or retrieval, but those are somewhat implied. Sufficient for a basic 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 83%, so most parameters already have descriptions in the schema. The description repeats the billing requirement for npub but adds no extra meaning for other parameters. 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 'Add a URL attachment to a thought' clearly states the action and resource. It is specific and not a tautology. However, it does not explicitly distinguish from the sibling tool 'brain_add_file_attachment', which is a closely related alternative.

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

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

The description only mentions a prerequisite (requires npub) but provides no guidance on when to use this tool vs alternatives, or when not to use it. The sibling 'brain_add_file_attachment' exists but is not 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?

No annotations are provided, so the description carries full burden. It implies read-only behavior ('check', 'polls') but does not explicitly state that no state is modified, nor does it disclose authentication requirements or potential errors.

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

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

The description is short and to the point: three sentences with no unnecessary words. It efficiently conveys the purpose and method.

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 presence of an output schema, the description covers the main purpose and possible statuses. However, it omits parameter details and error scenarios, making it incomplete for full agent comprehension.

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

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

Schema description coverage is 0%, and the description only implicitly explains authority_npub via 'at a chosen Authority'. The dpop_token parameter is not mentioned at all, leaving the agent uninformed about its purpose.

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

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

The description clearly states the verb 'check', the resource 'adoption-request status', and the context 'at a chosen Authority'. It distinguishes this tool from siblings like brain_request_adoption or brain_get_operator_onboarding_status.

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

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

The description mentions it is 'Free' and 'polls the Authority MCP-to-MCP', but does not provide explicit guidance on when to use this tool versus alternatives, nor does it specify prerequisites or exclusions.

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

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

No annotations provided, so description carries the burden. It mentions credit billing and automatic link resolution, but omits key behavioral traits: error handling, idempotency, what happens if note doesn't exist, and whether appending is at the end. Lacks full disclosure.

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 excessively long with a detailed style guide that is not directly relevant to the tool's function. The first sentence is sufficient; the rest should be in documentation. Not 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?

Despite having an output schema, the description lacks completeness about functional behavior: success indicators, error conditions, and whether append is at the end. The focus on stylistic rules leaves gaps in actionable information for the agent.

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

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

Schema coverage is 80%, so most parameters already have descriptions. The description adds no additional parameter semantics beyond what the schema provides. The note style and linking info are not parameter-specific.

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 first sentence clearly states the verb 'Append' and resource 'existing note'. However, the description dwells on note style and linking guidelines, which dilute the clarity. It does not specify whether append means at the end or elsewhere.

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

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

No guidance on when to use this tool versus alternatives like brain_create_or_update_note. The only usage hint is 'Requires npub for credit billing', but no when-not or exclusion criteria.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions that the tool accepts BrainQuery including destructive clauses (DELETE, CREATE, etc.) and requires an npub for billing, but it does not explicitly state that it can modify data or that the 'confirm' parameter is required for deletion. The agent is not adequately warned about potential 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, consisting of two sentences that front-load the core purpose and key requirement (npub). Every sentence adds value, with no wasted words.

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

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

Given the tool's complexity (a general query interface with read/write capabilities) and the presence of many sibling tools, the description is somewhat brief. It lacks guidance on safety, prerequisite knowledge (e.g., BrainQuery syntax), and when to use it versus other tools. However, the output schema (not shown) may compensate for some gaps.

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

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

Schema description coverage is 80%, so the schema already explains most parameters. The description adds value by clarifying that npub is for credit billing and that the query parameter accepts BrainQuery, but it does not explain confirm, brain_id, or dpop_token beyond 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 states it is the 'primary tool for pattern-based operations on TheBrain' and mentions BrainQuery (BQL), a Cypher subset. This clearly identifies the tool's purpose as a general query interface, distinguishing it from more specific sibling tools like brain_search_thoughts or brain_get_thought. However, 'pattern-based operations' is somewhat vague and could be more precise.

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

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

The description calls it the 'primary tool for pattern-based operations,' which implies it should be used for complex queries, but it does not explicitly state when to use this tool versus alternatives like brain_search_thoughts for simple searches or brain_get_thought for direct retrieval. No exclusions or when-not-to-use guidance is provided.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool checks balance and returns sats available, explains consequences of zero balance, and clarifies the nature of the balance. No side effects are implied.

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

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

The description is concise yet informative, starting with the main purpose, then details on return value, condition for zero balance, and clarification. Every sentence adds value.

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

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

Given the simplicity (no params) and the presence of an output schema, the description is complete. It covers what the balance is, how it is used, and what to do when it runs out.

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

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

The tool has no parameters (schema coverage 100% trivially). The description adds meaning by explaining the balance's purpose and consequences, beyond the empty schema.

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

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

The description clearly states the tool checks the operator's tax balance at the Authority. It specifies the resource and action, and distinguishes itself from siblings by noting it is the operator's own funding, not a patron balance.

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

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

The description explains when to use (to check balance for certifying patron purchases) and what to do if balance is zero (call purchase_credits). It does not explicitly mention when not to use or compare to alternatives, but provides sufficient 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, description discloses that the tool is free (no credits required) and requires a kind-27235 Nostr event as proof of npub ownership. Addresses security rationale. Could mention behavior on invalid input, but overall sufficient for a read operation.

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

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

Well-structured with three clear paragraphs: purpose, distinction, and important notes. Front-loaded with the action. Could slightly condense the second and third paragraphs, but still efficient.

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

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

For a simple two-parameter tool with an output schema, the description covers purpose, differentiation from siblings, cost, authentication, and security rationale. No 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?

Schema has 100% coverage with descriptions. Description adds context: specifies that dpop_token must be a kind-27235 Nostr event signed by npub, and explains why proof of ownership is required. This goes beyond schema.

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

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

Clearly states the tool checks a patron's credit balance at this operator. Specifies the balance type (spending balance from Lightning purchases). Distinguishes from sibling tool brain_check_authority_balance by explicitly naming the alternative.

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

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

Provides explicit guidance: when to use (check patron spending balance), when not to use (for operator's own balance, use authority_check_balance). Also notes it is free and requires proof of npub ownership, setting clear prerequisites.

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

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

With no annotations, the description carries the burden. It discloses that the tool is free and requires proof of npub ownership, but does not discuss other behavioral traits like idempotency, rate limits, or side effects. Acceptable but not comprehensive.

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

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

Three sentences cover purpose, timing, cost, and auth. Extremely concise with no filler. Information is front-loaded 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 output schema exists (so return values are covered), the description adequately covers purpose, usage sequence, cost, and security requirement. No gaps for a check-status tool.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description does not add additional semantic value beyond noting that invoice_id comes from purchase_credits, which is contextual rather than parameter detail.

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 ('Check the payment status of a Lightning invoice') and specifies the resource (invoice). It also provides context linking it to purchase_credits, distinguishing it from sibling tools that handle other 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?

Explicitly states when to call ('after paying the invoice from purchase_credits'), and mentions prerequisites (proof of npub ownership). It does not list alternatives, but the context is sufficient for a check 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 burden. It states the tool is free ('no credits required') and previews costs, but does not mention idempotency, rate limits, or side effects. It adds some behavioral context but is not comprehensive.

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

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

Two sentences with no wasted words. First sentence front-loads the purpose, second adds detail. Extremely concise and structured effectively.

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

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

Given the existence of an output schema (not shown), the description adequately explains what the tool returns (base cost, constraint effects). However, it does not provide any usage context or prerequisites beyond what is in the schema, leaving some gaps for a pricing preview 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 50% (only tool_id and tool_kwargs have descriptions). The tool description does not add meaning for the undocumented parameters (npub, dpop_token) and does not compensate for the gaps. It relies on the schema's existing 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 it 'previews effective cost of a tool call' and explains what it shows (base cost, constraint effects). This verb+resource combination distinguishes it from sibling tools 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 implies usage when you want to know cost before calling a tool, but does not explicitly state when not to use it or mention alternatives. The context is clear but lacks exclusions.

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

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

With no annotations, the description carries the burden and discloses key traits: it is free, has no side effects, does not evict cache or touch relays. This is sufficient for a safe read operation.

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

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

The description is three sentences, each adding unique value: function, analogy/use case, and safety guarantees. No redundant or wasted words.

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

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

Given the tool's simplicity, the description covers function, use case, side effects, and parameter origins. The output schema exists to handle return value details, so completeness is high.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal parameter context beyond the schema (e.g., dpop_token from request_npub_proof/receive_npub_proof), but the schema already includes that.

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

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

The description clearly states the tool checks validity of a cached dpop_token, distinguishing it from similar tools by explicitly referencing the npub-proof flow and providing a concrete use case ('will my next paid call accept this dpop_token?').

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 (before a paid call to avoid burning credits on failure) and notes the tool is free with no side effects. It doesn't explicitly state when not to use, but the context is sufficient for an agent to decide.

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

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

No annotations provided, so description carries full burden. It mentions credit billing requirement but omits other behavioral traits: mutation of data, potential for errors if thoughts don't exist, or whether operation is idempotent.

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

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

Single sentence, no fluff. Could be slightly expanded to include key behavioral notes, but it's appropriately short.

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 11 parameters and complexity, the description is minimal. It omits default behavior (e.g., brain_id uses active brain) and expected output. Even with output schema existing, more context on intended use would help.

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

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

Schema coverage is 91%, so parameter descriptions exist. The description adds 'by ID' but that's already in schema. It does not clarify e.g., relation type meanings beyond schema, so value-add is marginal.

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 creates a relationship between two thoughts by ID. This distinguishes it from sibling tools like brain_create_thought (creates thought) and brain_update_link (updates existing relationship), though it does not explicitly differentiate.

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

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

The only guidance is that npub is required for credit billing. There is no indication of when to use create vs update, prerequisites (thoughts must exist), or alternatives among siblings.

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

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

No annotations are provided, so the description carries full burden. It discloses that credit billing requires npub, explains wikilink resolution behavior (including unresolved links being returned), and implies upsert behavior (create or update). This goes beyond a simple description, though it omits potential destructive overwrite details.

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 lengthy and includes extensive style guidelines (e.g., on bold usage, wikilinks) that are more appropriate for agent instruction than tool description. The core purpose is front-loaded, but the verbosity reduces conciseness.

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

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

Given the presence of an output schema and high schema coverage, the description covers essential behavioral aspects (billing, link resolution). It lacks return value explanation, but output schema compensates. Completeness is adequate for a create/update 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 80% (4 of 5 parameters have descriptions). The description adds marginal value beyond the schema: it reiterates npub requirement and provides style guidelines for the markdown content, but does not enrich parameter meaning substantially.

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

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

The description clearly states it creates or updates a note with markdown content. The name and description together convey the verb (create/update) and resource (note). While it doesn't explicitly differentiate from siblings like brain_append_to_note, the distinction is implied by the name and core action.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to create vs update, or vs brain_append_to_note). It mentions a prerequisite (npub) but lacks context on when this tool is appropriate or not.

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 states 'Create' but doesn't disclose side effects, idempotency, limits, or consequences beyond the npub requirement. The schema's 'kind' parameter has behavioral implications not elaborated in the description.

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, front-loaded sentences with no fluff. Every word adds value: the first sentence states purpose and key options, the second adds the critical prerequisite. No wasted text.

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

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

Given 12 parameters and an output schema, the description is adequate but omits important aspects like access type (ac_type), brain selection (brain_id), and source linking. The schema fills gaps, but the description could be more holistic.

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 92%, so baseline is 3. The description only lists broad parameter categories (type, color, label, parent link) without adding meaning beyond what the schema already provides. No additional examples or clarifications.

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 'Create a new thought' with specific optional attributes (type, color, label, parent link), distinguishing it from sibling tools like brain_update_thought or brain_get_thought. The verb-resource combination is precise 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 only mentions the npub requirement for credit billing but gives no guidance on when to use this tool versus alternatives like brain_morph_thought, brain_create_link, or brain_create_or_update_note. Missing explicit usage context or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses that deletion requires npub for billing, implying a credit cost, but does not detail side effects (e.g., irreversibility, cascading deletions) or error conditions.

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

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

The description is extremely concise, consisting of two sentences that convey the essential purpose and a key requirement 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?

While the description covers core purpose and billing, it lacks details on post-deletion behavior, error handling, or return values (though an output schema exists). Given the simple nature of a delete action, the description is adequate but could be more informative.

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

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

The description adds no parameter information beyond what is in the input schema. The schema already describes npub, brain_id, and attachment_id, but dpop_token lacks description; the description does not fill this 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 specifies the verb ('Delete') and resource ('an attachment'), and it distinguishes from sibling delete tools (e.g., brain_delete_thought, brain_delete_link) by focusing on attachments.

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

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

The description mentions a prerequisite ('Requires npub for credit billing'), which provides some usage context, but it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Discloses cascading deletions, orphan references become no-ops, and authorization requirement. Without annotations, this fully covers behavioral traits.

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

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

Three concise paragraphs; first sentence states action. Could be slightly more compact but no unnecessary text.

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

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

Explains cascading behavior and authorization. Missing parameter descriptions, but output schema exists to cover return values.

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

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

Schema coverage is 0% and description provides no additional meaning for coupon_id or dpop_token. Parameters are not explained.

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 'Delete a coupon' and explains cascading effects. Distinguishes from sibling tools like brain_update_coupon and brain_list_coupons.

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

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

Explicitly states 'RESTRICTED to operator — requires proof' and warns about cascading effects. No explicit mention of when not to use or alternatives, but context is clear.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It states the action is permanent and cannot be undone, and explains the billing requirement. This is valuable, though it omits details like authorization checks or error handling.

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

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

Extremely concise: two short sentences covering all essential points (action, permanence, billing requirement). No wasted words; 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 tool's simplicity and the existence of an output schema (reducing need to describe return values), the description adequately covers the core operation, permanence, and prerequisite. It could mention that the link must exist, but overall it is sufficiently complete.

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

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

Schema description coverage is 75% (3 of 4 parameters described). The description adds no extra meaning beyond what the schema provides, simply echoing 'by ID' and 'requires npub'. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'delete' and the resource 'link', with additional emphasis on permanence. It distinguishes from other delete tools (e.g., brain_delete_thought, brain_delete_attachment) by specifying the resource, making it 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 important usage context: the operation is irreversible and requires an npub for credit billing. However, it does not explicitly guide when to use this tool versus alternatives (e.g., brain_update_link or brain_delete_attachment), leaving the agent to infer from the resource name.

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

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

With no annotations, the description carries full burden. It discloses that the operation is a write, requires proof of ownership, and is free. It adds value by clarifying the sensitive nature of the vault, though it doesn't specify idempotency or field existence 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 very concise, using two sentences and a break to clearly state purpose, scope, and requirement. 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?

Given the presence of output schema, return values are covered. The description addresses purpose, auth requirement, and scope (single field). It lacks mention of error behavior but is otherwise sufficient for a well-defined delete operation.

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

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

Schema coverage is 100%, and the description largely repeats the schema details (npub, field, dpop_token). It does not add significant new context about parameter usage, 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 'Remove a single patron credential field' and 'Deletes one field from stored credentials', providing specific verb and resource. It distinguishes from sibling tools like brain_update_patron_credential by specifying deletion without affecting other 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 mentions 'Proof of npub ownership is required' and that it is a write to sensitive vault, giving context on when to use. However, it does not explicitly compare to related siblings like brain_forget_credentials, which would improve 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?

Discloses permanence and npub requirement, but with no annotations provided, the description should cover more behavioral traits such as effects on related data or error states.

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 no filler, front-loading the key action and constraints.

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

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

Covers the core deletion action but lacks details on return values, error handling, or side effects, despite having an output schema.

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

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

Schema description coverage is 75% and already includes parameter descriptions. The description adds no significant meaning beyond 'by ID' and 'requires npub for billing', which is also in the schema.

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

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

Description clearly states the verb 'delete', resource 'thought', and key constraints (permanent, requires npub). Distinguishes from sibling tools like 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?

Implies usage for permanent deletion with caution ('Cannot be undone'), but does not explicitly state when not to use or mention alternatives like brain_update_thought.

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

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

With no annotations, the description carries full burden. It discloses the npub requirement for billing but says nothing about side effects, success behavior, or whether the operation is destructive. Minimal behavioral disclosure 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 sentences, front-loaded with the primary purpose. Every word earns its place. Could be more structured but is appropriately concise.

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

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

Despite having an output schema, the description lacks explanation of the composite creation process, relationship between parameters, or what the output contains. For a tool with 7 parameters, the description is too minimal.

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%), so baseline is 3. The description adds context by naming the entities (Event, Person, Day) tying together date, person, and event_name, but doesn't add detailed semantics beyond what the schema already provides.

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

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

The description clearly states the action (Create) and resource (Event+Person+Day). It distinguishes from siblings by highlighting the composite nature, but could be more explicit about what this composite entails.

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

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

No guidance on when to use this tool versus other create tools like brain_create_thought or brain_create_or_update_note. The description implies usage for creating all three entities together, but no explicit when-not or alternatives.

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

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

With no annotations provided, the description carries full burden. It discloses that the operation is cosmetic (non-destructive to the coupon), free, and requires npub proof. This adequately covers key behavioral traits for a simple removal action.

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

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

Three concise sentences: first states the action, second explains the cosmetic nature, third notes the requirement. Every sentence adds value without 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 straightforward removal tool with an output schema present, the description covers the essential behavioral details. It explains the effect and requirement, but it could more explicitly list the parameters. The output schema likely compensates for return value documentation.

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% description coverage, so the description must compensate. It only mentions 'npub' in context but does not explain the meaning or format of npub, coupon_id, or dpop_token. No parameter-level guidance is given, leaving the agent to guess.

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 'Remove' and clearly identifies the resource as 'a coupon from this patron's redemption list.' It distinguishes the tool from brain_delete_coupon by noting the operation is cosmetic, so an agent can see it's different from a true deletion.

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

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

The description provides clear context: it's cosmetic, the coupon still exists, and the patron can re-redeem later. It also mentions the prerequisite 'requires proof of npub.' However, it does not explicitly tell the agent when to avoid this tool or suggest alternatives like brain_delete_coupon.

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

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

With no annotations, the description fully bears transparency. It explicitly states the destructive nature ('a deletion is as destructive as a write') and the requirement for proof of npub ownership via dpop_token. This adds critical behavioral 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?

The description is three sentences, each adding unique information: action, usage nuance, and behavioral warning. No extraneous content. Front-loaded with the verb 'Delete'.

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

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

Given the presence of an output schema, the description adequately covers purpose, usage, and behavioral traits. It could mention reversibility or idempotency, but the destructive note suffices for a mutation tool.

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

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

Schema coverage is 100% but the description adds value by clarifying the npub parameter: for operator vs patron credentials. This distinction is not present in the schema description, enhancing parameter understanding.

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

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

The description clearly states the action: 'Delete vaulted credentials for a specific service and npub.' It distinguishes between operator and patron credentials, specifying which npub to use in each case. This clarity differentiates it from related 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 provides guidance on when to use the tool for operator vs patron credentials. However, it does not explicitly mention when not to use it or suggest alternatives (e.g., brain_delete_patron_credential), missing some contextual exclusion.

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 only mentions a billing requirement, omitting details like side effects (presumably read-only), idempotency, or rate limits. More behavioral context is needed.

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 no filler. 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?

Despite having an output schema, the description fails to explain the purpose of dpop_token, what metadata is returned, or billing details. For moderate complexity (4 params), more context is needed.

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

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

Schema description coverage is 75% (3 of 4 parameters described). The description reinforces npub requirement but adds no new meaning beyond schema descriptions. The undocmented dpop_token is not explained, but baseline is 3 due to high coverage.

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

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

The description clearly states it retrieves metadata about an attachment, distinguishing it from siblings like brain_get_attachment_content (content retrieval) and brain_add_* (creation).

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

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

The description mentions the npub requirement for billing but does not provide guidance on when to use this tool versus alternatives like brain_get_attachment_content or brain_list_attachments. Usage context is implied but not 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. It only mentions the npub requirement and that it gets binary content. It does not disclose potential side effects, performance implications, error handling, or whether it is a read-only operation. The description is insufficient for an agent to understand behavioral traits.

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

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

The description is two short sentences, front-loaded with the main action. There is no superfluous text; every element earns its place. This is ideal for conciseness.

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

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

Given the tool has 5 parameters (1 required) and an output schema, the description is minimally adequate. It does not explain return values (though output schema may cover that) or provide context about when to use this tool versus similar ones. More context on typical usage and limitations would improve completeness.

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

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

Schema description coverage is 80%, so baseline is 3. The description adds no parameter meaning beyond the schema; it merely restates the npub requirement already documented in the schema. Thus, it does not 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 clearly states the action ('Get') and resource ('binary content of an attachment'). It distinguishes from sibling 'brain_get_attachment' by specifying 'binary content'. However, it does not explicitly differentiate from similar siblings, leaving some ambiguity.

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

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

The description mentions a prerequisite ('Requires npub for credit billing') but provides no guidance on when to use this tool versus alternatives like 'brain_get_attachment'. No context about typical use cases or exclusions is given.

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

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

No annotations exist, so the description carries the full burden. It discloses the billing requirement, which is a behavioral trait. However, it does not specify whether the tool is read-only, idempotent, or what errors may occur. The disclosure is 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 a single, well-front-loaded sentence with no extraneous information. Every word serves a purpose.

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

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

Given the tool's simplicity and the presence of an output schema (which presumably details return values), the description is largely adequate. However, it could benefit from a brief note on when to use this tool versus other 'get' tools (e.g., brain_get_brain_stats), which would improve contextual completeness.

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

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

Schema coverage is 67% (two out of three parameters have descriptions). The description reiterates that npub is required for billing, which is already in the schema, but adds no new meaning for brain_id or dpop_token. The schema does most of the work, so the description adds minimal value.

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

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

The description clearly states the tool's action ('Get details about a specific brain'), using a specific verb and resource. It distinguishes itself from sibling tools that retrieve other entities (e.g., brain_get_brain_stats, brain_get_thought), making its purpose unmistakable.

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

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

The description mentions the npub requirement for credit billing, which serves as a usage condition. However, it does not explicitly state when to use this tool over alternatives or provide context on prerequisites beyond npub. The guidance is clear but incomplete.

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

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

The description discloses that credit billing is required (implying a non-free operation), but lacks other behavioral details like idempotency, side effects, or data scope. Since no annotations exist, the description only partially fulfills the transparency burden.

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

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

The description is a single sentence with no fluff, efficiently conveying purpose and a key requirement. 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?

Despite having an output schema, the description does not specify what statistics are returned (e.g., thought count, connections). This omission reduces completeness given the tool's name implies a summary, and agents may need to know if it matches their need.

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 67% (npub and brain_id have descriptions). The description text adds no additional meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and resource 'statistics about a brain'. It is distinct from sibling tools like brain_get_brain which retrieve the brain object, not statistics.

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

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

The description mentions a prerequisite ('Requires npub for credit billing') but provides no guidance on when to use this tool over alternatives, such as brain_get_brain or brain_get_thought. No when-not or alternative suggestions.

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

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

Discloses that npub is required for credit billing, a behavioral trait beyond schema, but no annotations exist to contradict. Lacks details on read-only nature, rate limits, or error scenarios.

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: one for purpose, one for a key requirement. No redundant information, 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?

Adequate for a simple retrieval tool with output schema, but lacks guidance on when to use over other link or detail tools, and missing context like required authorization.

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?

75% schema coverage provides baseline 3; description adds slight value by reinforcing npub's billing purpose, but does not elaborate on other parameters beyond schema.

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

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

The description clearly states the verb 'Get details' and the resource 'a specific link', distinguishing it from sibling tools like brain_create_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?

Description provides implied usage for retrieving link details but lacks explicit when-to-use vs alternatives or exclusions, such as not searching for links.

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 disclose behavioral traits. It only says 'Get modification history' and 'Requires npub for credit billing,' but does not mention side effects, rate limits, or error conditions. The read-only nature is implied but not explicit, and there is inconsistency between the schema (default empty string) and description ('Required').

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, front-loaded with the main action 'Get modification history for a brain.' It wastes no words, but the brevity leaves out important details. It is appropriately sized for a simple tool.

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

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

Given the complexity (6 parameters, many optional) and the presence of an output schema, the description should provide more context about default behavior (e.g., time range, number of logs) but fails to do so. The description is too minimal for a retrieval tool with multiple optional filters.

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 high coverage (83%), so the description adds value beyond it primarily by clarifying that npub is for billing. This adds context to one parameter. The other parameters are well-described in the schema, so the marginal contribution is moderate.

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

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

The description clearly states the verb 'Get' and resource 'modification history for a brain', making the purpose evident. It distinguishes from sibling tools like brain_get_brain by specifying 'modification history', though it does not explicitly contrast with other get_* 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 mentions that npub is required for credit billing, which provides a prerequisite. However, there is no guidance on when to use this tool versus alternatives (e.g., other brain_* tools) or when not to use it. The context is minimal.

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 that the operation is a read, returns specific fields, and may return empty profile. However, it does not specify error handling for invalid npub, rate limits, or response format details.

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, front-loaded with the verb and resource. Every sentence adds value: what it does, that it's free, and what it returns. No fluff.

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

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

For a tool with one optional parameter and an output schema (present), the description covers the purpose, authorization, return fields, and edge case (empty profile). The output schema explains the structure, so no further detail needed.

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 description coverage is 0%, so the description must clarify the parameter. It mentions 'npub' in the first sentence, indicating the parameter is a nostr public key. The default empty string is noted, but no additional format or validation details are provided beyond the schema.

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

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

The description clearly states the verb 'Read', the resource 'npub's public Nostr profile', and the protocol (NIP-01 kind-0 metadata). It distinguishes from the sibling 'brain_publish_nostr_profile' which is for writing.

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

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

The description mentions 'Free, no proof — the data is already public on relays', indicating no authentication is needed. It implicitly suggests using this for reading, but does not explicitly state when not to use it or alternatives beyond the sibling list.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool generates a cryptographic proof, but does not mention any side effects, permissions required, or performance implications. The description is adequate but minimal, neither contradicting nor fully detailing behavior.

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

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

The description is a single sentence with no wasted words. It front-loads the key action and resource, 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 the tool's moderate complexity (crypto proof) and the presence of an output schema (handling return values), the description provides sufficient context for an agent to understand the tool's purpose. It could mention the proof format or verification steps, but is complete enough for selection and 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% and both parameters ('npub', 'notarization_id') have clear descriptions in the schema. The tool description adds context by linking to 'patron's balance', but does not significantly enhance parameter meaning beyond schema. Baseline score applies.

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

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

The description clearly states the tool generates a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot. It uses a specific verb ('Generate') and resource ('Merkle inclusion proof'), distinguishing it from sibling tools like brain_list_notarizations (list notarizations) and brain_notarize_ledger (create notarization).

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

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

The description provides no guidance on when to use this tool versus alternatives, such as first listing notarizations to obtain a notarization_id. It lacks prerequisites or context for usage, leaving the agent to infer the workflow.

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

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

No annotations are provided, so the description carries full burden. It only mentions billing requirement but does not disclose other behaviors (e.g., whether it modifies data, error handling, or what happens if npub is missing).

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

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

Two concise sentences, each adding value: purpose and a key requirement. No wasted words.

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

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

With an output schema present and moderate complexity (5 params, 1 required), the description adequately covers the basic operation but could add context about error cases or format defaults.

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%, and the description's mention of npub billing mostly repeats the schema description. No additional parameter semantics are provided 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 purpose with a specific verb ('Get') and resource ('note content for a thought'), distinguishing it from siblings like brain_get_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 clear context by mentioning the requirement of npub for credit billing, but does not explicitly state when to use vs. alternatives or when not to use.

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

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

No annotations provided, so description carries full burden. It describes a read-only reporting behavior without side effects. Does not mention auth or rate limits, but adequate for a simple status 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?

Three concise sentences: purpose, details, and alternative. No fluff; every sentence adds value.

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

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

Given zero parameters and an output schema present, description is complete enough: it explains what the tool does and when to use 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?

No parameters in schema, baseline is 4. Description adds no parameter info but explains the tool's purpose without needing 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?

Clearly states it reports configuration readiness for an operator, listing what it shows (configured/missing settings and how to deliver missing values). Also distinguishes from sibling tool for patron-level status.

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

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

Explicitly tells agent to use get_patron_onboarding_status for patron-level credential status, providing a clear alternative and exclusion condition.

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 values are never exposed, that the list of fields is sensitive (revealing integrations), and that authentication (dpop_token) is required. This goes beyond basic usage.

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 long, front-loaded with the core action, and each sentence adds value without redundancy. It is well-structured and easy to parse.

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

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

The tool is simple (2 params, no nested objects) and has an output schema, so the description does not need to explain return values. It covers purpose, limitations, security, and prerequisites comprehensively.

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

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

Schema description coverage is 100% (both npub and dpop_token are described in the schema). The description does not add meaningful new information about the parameters beyond what the schema already provides.

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

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

The description clearly states 'List stored patron credential field names (not values).' It specifies the verb (list) and resource (patron credential field names), effectively distinguishing from sibling tools like brain_update_patron_credential and 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: 'use this to verify which fields are configured.' It also mentions it is free and requires npub ownership proof. While it does not explicitly state when not to use or list alternatives, 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?

No annotations provided, so description carries the burden. Discloses that the tool reveals sensitive credential presence and requires authorization proof. Adds behavioral context beyond schema, though could explicitly state it is read-only.

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?

Well-structured with main purpose upfront. Five sentences are efficient, though slightly verbose. Each sentence contributes meaningful information 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?

Covers key context: service types (set-once vs dynamic), cost (free), and authorization requirement. Output schema exists, so not explaining return values is acceptable. Completeness is solid given tool complexity.

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

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

Schema already fully describes both parameters with 100% coverage. Description adds only that dpop_token serves as proof of ownership, which is a minor semantic addition. 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?

Clearly states 'Report a patron's credential readiness for this operator' and distinguishes between service types, making the purpose unambiguous relative to sibling tools like brain_get_operator_onboarding_status.

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

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

Provides context on when to use (checking credential readiness) and mentions proof of ownership requirement. However, lacks explicit exclusions or alternative tool suggestions, though the distinction between service types implicitly guides usage.

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

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

With no annotations, the description carries full burden. It discloses the self-initialization behavior when no model exists, which is a key side effect. The statement 'No economic data from code' further clarifies 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 extremely concise: two sentences with no wasted words. Purpose is front-loaded, and every sentence adds value.

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

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

Given zero parameters and an existing output schema, the description covers the essential behavioral detail (self-initialization). It could elaborate on what the pricing model contains, but output schema compensates.

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

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

The tool has no parameters, so schema coverage is trivially 100%. The description does not need to add parameter info; 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', which specifies the verb (get) and resource (pricing model). It distinguishes from sibling tools like brain_set_pricing_model and brain_reset_pricing_model.

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

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

The description indicates it is 'Free' and 'No economic data from code', providing context for when to use this read operation. However, it does not explicitly state when not to use it or mention alternatives, though siblings imply that.

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 disclose behavioral traits. It only mentions the credit billing requirement, but omits whether the operation is read-only, idempotent, or has side effects. The contradiction between the description stating 'Requires npub' and the schema not marking npub as required also undermines 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 extremely concise, consisting of a single sentence without extraneous words. However, it could be slightly more structured by separating the billing requirement into a separate sentence or 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?

The tool is simple (get tags) and an output schema exists, so the description does not need to explain return values. However, it lacks contextual details like whether the brain ID is required, how billing works, or any rate limits, making it only minimally complete.

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

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

Schema description coverage is 67%, and the description adds no new information beyond what is already in the schema for npub and brain_id. The dpop_token parameter lacks any description in either source. The description's claim that npub is required conflicts with the schema making it optional with a default, causing confusion.

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') and the resource ('all tags in a brain'), which is specific and unambiguous. It distinguishes from sibling tools like brain_get_thought or brain_get_types by explicitly targeting tags.

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 (e.g., brain_get_thought for thoughts). There is no mention of prerequisites or context, leaving the agent to guess appropriate usage scenarios.

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

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

No annotations are present, so the description bears the full burden. It indicates a read-like action ('Get details') but does not explicitly state that it is non-destructive, nor does it describe what 'details' are returned. The existence of an output schema partially mitigates this.

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

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

The description is extremely concise (one sentence), which is good for front-loading, but it may be too brief to be fully helpful. No superfluous content.

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

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

Given the complexity (4 parameters, no annotations) and the presence of many sibling tools, the description is insufficient. It lacks information about return values, usage context, and alternatives, making it incomplete for effective tool selection.

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 semantic value beyond the input schema's parameter descriptions. Schema coverage is high (75%), but the description fails to explain the dpop_token parameter or provide any additional context for the other 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 verb 'Get' and the resource 'details about a specific thought', making the purpose obvious. However, it does not distinguish from sibling tools like brain_get_thought_by_name or brain_get_thought_graph, which could lead to confusion.

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

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

The description mentions the npub requirement for credit billing but provides no guidance on when to use this tool versus alternatives (e.g., use brain_get_thought_by_name if searching by name). Context for usage is minimal.

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

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

No annotations provided, so description carries full burden. It discloses that it requires npub for billing and returns first match, but does not mention side effects, rate limits, or authentication details beyond npub. Adequate but minimal.

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

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

Single sentence with no waste. Front-loaded with purpose ('Exact name lookup'). 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 output schema exists (burden reduced), description explains primary operation and billing need. Does not clarify ordering of 'first' match, but overall sufficient for a straightforward lookup 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 75%, high enough that description adds little extra value. Description only reiterates npub requirement; does not explain brain_id or dpop_token beyond 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?

Description clearly states it performs exact name lookup and returns the first matching thought. The verb 'lookup' and resource 'thought' are specific, and it distinguishes from siblings like brain_search_thoughts which likely does fuzzy search.

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?

Implied usage for exact name match; mentions npub requirement for billing, but does not explicitly state when not to use or list alternatives. Context is clear but lacks exclusions.

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

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

No annotations provided, so the description must disclose behavioral traits. It only mentions credit billing, not whether the operation is read-only or any 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?

Extremely concise at two sentences; front-loaded with the verb and resource. 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 complexity (5 params, output schema, siblings), the description is minimal. It does not clarify what a 'connection graph' entails or any filtering, but output schema compensates somewhat.

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 (80%), so the baseline is 3. The description adds no new information beyond the schema's own parameter 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 it retrieves a thought's full connection graph, using a specific verb and resource. It distinguishes from the paginated sibling tool by specifying 'full graph'.

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?

Only mentions one prerequisite (npub for billing) but does not explain when to use this tool versus alternatives like the paginated version or get_thought.

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

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

No annotations are present, so the description must carry the burden. It discloses the billing requirement (npub for credit billing) and pagination behavior. However, it does not specify whether the tool is read-only or modifies state, nor does it describe error or rate-limiting 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?

Two sentences, front-loaded with purpose, and no extraneous 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?

The description covers the core purpose and billing requirement but lacks context about when to prefer this paginated version over the non-paginated sibling, and does not explain the cursor mechanism or result shape (though output schema exists). Adequate but with clear gaps.

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

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

Schema description coverage is high (88%), so the schema already documents parameters well. The description adds minimal parameter insights beyond restating the npub requirement. No additional semantic guidance beyond schema.

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

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

The description clearly states it performs cursor-based paginated traversal of a thought's connections, which distinguishes it from the sibling tool brain_get_thought_graph (likely non-paginated). The verb 'traversal' and resource 'thought's connections' are specific and unambiguous.

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

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

The description implies use for paginated access to connections but does not explicitly state when to use this tool versus alternatives (e.g., brain_get_thought_graph for non-paginated). No when-not-to-use or context provided.

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

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

Without annotations, the description only discloses the credit billing requirement (npub) but does not elaborate on read-only nature, idempotency, or other behavioral aspects beyond the basic 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 extremely concise with two sentences, each earning its place: the first states the action, the second adds a key requirement.

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 simple list operation, an output schema exists, and the description covers the essential purpose and a critical prerequisite, making it mostly complete.

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

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

Schema description coverage is 67%, and the description adds no additional meaning beyond what the schema already provides for the npub and brain_id 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 verb 'List' and the resource 'thought types defined in the brain', distinguishing it from sibling tools like brain_get_tags or brain_get_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 implies usage through its specific purpose but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among the many sibling tools.

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

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

No annotations provided, so description must carry full burden. Indicates read-only listing but lacks details on pagination, limits, ordering, or response structure beyond what the output schema might provide. Does not mention if it lists only accessible attachments or all.

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

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

Two sentences, front-loaded with purpose. No wasted words.

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

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

Tool is simple and has an output schema, so description covers purpose and billing prerequisite. However, lacks context on authentication (is npub enough?), data freshness, or any filtering capabilities. Adequate but not comprehensive for a tool with no annotations.

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

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

Schema description coverage is 75%, but the description adds no new meaning beyond the schema's parameter descriptions. The npub requirement is already noted in schema; dpop_token is undocumented in both. No parameter format, constraints, or usage examples 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?

Explicitly states 'List all attachments for a thought' with clear verb-resource-scope. Distinguishes from sibling tools like brain_get_attachment (single) and brain_add_file_attachment (adding).

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 one usage requirement ('Requires npub for credit billing') but no guidance on when to use this tool vs alternatives like brain_get_attachment_content or brain_get_attachment. No explicit when-not or preferred scenarios.

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

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

No annotations are present, so the description carries full burden. It only states 'List available brains' without disclosing whether it is read-only, requires authentication, or any side effects. Given the lack of annotations, this is insufficient.

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

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

The description is concise (one sentence) but minimally informative. It is not structured and could benefit from additional context without losing conciseness.

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

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

Given the complexity (2 parameters, many sibling tools), the description is incomplete. It does not explain what 'brains' are, how listing works, or what the output contains. The output schema exists but the description should provide high-level 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 50% (npub described, dpop_token not). The tool description adds no additional parameter meaning. It does not compensate for the undocumented parameter, nor does it clarify the role of npub beyond the schema's own 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 'List available brains' clearly states the verb (List) and resource (brains). It distinguishes from siblings like brain_get_brain (singular) and brain_set_active_brain. However, the term 'brains' is domain-specific and could be clarified.

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_brain or brain_set_active_brain. It does not indicate prerequisites or context for listing.

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 safe behavior ('Free, no side effects') and explains that tool_id remains constant while mcp_name may change on renames, which is key 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 appropriately sized with multiple sentences, each adding value. It front-loads the purpose and is structured logically, though it could be slightly more concise.

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

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

Given the output schema exists and there are no parameters, the description fully covers purpose, behavioral traits, and use cases. It is complete for a simple list tool.

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

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

There are zero parameters, so baseline is 4. The description does not need to add parameter information, and schema coverage is 100%.

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 'Return canonical (tool_id, mcp_name, …) for every registered tool,' specifying verb and resource, and distinguishes it from sibling tools by emphasizing its role as the authoritative source for tool identification.

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

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

The description explicitly identifies its usage: 'The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools,' and gives a specific reconciliation use case. However, it does not mention when not to use it or provide alternative tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is free and returns type, category, description, and parameter specs, implying it is a read-only operation. No side effects or authentication needs are mentioned, but the description is sufficient for a safe listing 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 concise, well-structured, and front-loaded with the main action. Every sentence adds value, with bullet points for the returned fields.

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

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

Given the tool has no input parameters, a clear output schema (likely exists), and the description specifies the returned fields, it is complete for the task. An agent can correctly invoke this tool without missing information.

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 no input parameters, and schema description coverage is 100%. The description adds no parameter info because none are needed; baseline score for 0 parameters is 4.

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

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

The description clearly states it lists all available constraint types and their parameter schemas, with a specific verb (list) and resource (constraint types). It distinguishes itself from sibling tools by being a specialized listing tool for constraint types.

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

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

The description mentions it's free with no credits required, which is helpful usage context, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear enough for an agent to infer its use.

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

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

With no annotations provided, the description bears the full burden. It reveals that the tool is restricted to operators and requires proof, which is critical behavioral context. It also explains the times_redeemed counter and its use in a progress bar. However, it does not mention error handling or pagination.

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 plus a short note. The main purpose is front-loaded, and every sentence adds value (ordering, counter detail, restriction). 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?

Given the existence of an output schema, the description does not need to fully explain return values, but it does highlight the progress bar field. However, it completely omits explanation of the sole input parameter dpop_token, leaving a significant gap. The restriction and ordering are well covered.

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 only parameter dpop_token is not described in the tool description, and the input schema provides no description (0% coverage). The agent receives no guidance on what dpop_token is for, severely hindering correct invocation.

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

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

The description clearly states 'List every coupon this operator has minted (newest first)', specifying the verb (list), resource (coupons), and ordering (newest first). It distinguishes this tool from siblings like brain_mint_coupon and brain_delete_coupon by focusing on listing.

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: it is for the operator's own minted coupons and requires proof (authentication). It implicitly tells when to use (when you need to see all minted coupons) but does not explicitly state when not to use or compare to alternatives like brain_list_my_coupons.

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

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

No annotations provided, so description carries full burden. Reveals that it returns both active and exhausted redemptions with specific status values, and notes it is free and requires npub proof. Good disclosure.

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, no filler. Action first, then return details. Perfectly 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?

Covers what is listed, scope, return statuses, and access requirements. Output schema exists to handle return structure, so description need not detail fields further. Slight gap: no mention of pagination or sorting, but acceptable for a simple 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 0%, so description must compensate. It mentions npub is required but does not explain dpop_token or add format/meaning beyond the schema. Minimal value added.

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'), the resource ('coupons this patron has redeemed'), and the scope ('on this operator'). Distinguishes from sibling 'brain_list_coupons' via the 'my' qualifier.

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

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

Specifies prerequisite ('requires proof of npub') and cost ('Free'). Does not explicitly state when not to use or compare with siblings like brain_list_coupons, but the personal scope is self-evident.

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 does not disclose any behavioral traits beyond what is obvious from the name 'list'. With no annotations provided, the agent has no information about read-only nature, rate limits, or potential 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, short sentence that is easy to read. However, it could include additional context without becoming verbose.

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

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

For a simple list tool with an output schema, the description is adequate but vague about 'recent'. It does not explain what constitutes a record or the ordering, but the output schema likely covers the structure.

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 parameters are documented. The description adds no extra meaning beyond the schema, which is the baseline for this scenario.

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

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

The description clearly states the tool lists 'recent Bitcoin notarization records' with a specific verb and resource. It distinguishes from sibling tools like brain_get_notarization_proof and brain_notarize_ledger, but could be more precise about 'recent'.

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

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

No guidance on when to use this tool versus alternatives. For example, if a user needs a specific notarization proof, they should use brain_get_notarization_proof, but this is not 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?

No annotations are present, so the description carries the full burden. It only states 'Create a new...' but does not disclose any behavioral traits such as idempotency, ownership implications, or what happens upon creation (e.g., whether it enforces uniqueness on the name).

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

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

The description is a single, complete sentence with no extraneous words. 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?

Given the tool's complexity (7 parameters, 4 required) and lack of annotations, the description is insufficient. It does not address return values, error conditions, or uniqueness constraints, relying entirely on the output schema for return information.

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 (86%). The description adds value by specifying 'operator-owned', which clarifies the ownership scope and implies name uniqueness. This contextual detail goes 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 operator-owned discount coupon'). It is specific and understandable, but does not explicitly differentiate from sibling tools like brain_update_coupon or 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 guidance on when to use this tool versus alternatives (e.g., brain_update_coupon, brain_list_coupons). No context about prerequisites or typical scenarios is given.

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

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

With no annotations, description carries full burden. It discloses atomicity, npub requirement, replacement semantics, and that it does not add additional parent. Could mention lack of change if no new_type_id/new_parent_id, but overall transparent 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?

Two paragraphs, front-loaded with purpose, each sentence adds value. No superfluous text. Efficiently covers requirement, core behavior, and differentiation from sibling.

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

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

Given the tool has an output schema (unknown content) and is a mutation with two optional operations, the description adequately covers purpose, key behaviors, and alternatives. Could mention error conditions or prerequisites beyond npub, but sufficient for agent decision-making.

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

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

Schema coverage is 83%, so baseline 3. Description adds value by explaining npub requirement for billing and clarifying that new_parent_id replaces all current parents. This goes beyond individual parameter descriptions, enhancing 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 clearly states the tool does atomic reparenting and/or retyping of a thought, using specific verbs and resource. It distinguishes itself from update_thought, which covers additional operations like setting name/label.

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 mentions requirement for npub for billing and directs to update_thought for combined operations like setting name/label. Clarifies that reparenting replaces existing parent, not adds. Provides clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description fully conveys key behaviors: it is a background task, free, and involves a blockchain submission with a known time delay. It implies mutation by submitting to Bitcoin, which is appropriate 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 extremely concise (two sentences), front-loads the main action in the first sentence, and contains no unnecessary words or redundancy.

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

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

Given the tool's simplicity (no parameters), the presence of an output schema, and the description covering operator-only usage, cost, and timing, the description is fully complete for an AI agent to understand invocation and behavior.

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

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

The tool has no parameters, and the schema coverage is 100%. The description adds no parameter information because none is needed, earning the baseline score for zero parameters.

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

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

The description clearly states the action: building a Merkle tree of patron balances and submitting the root to Bitcoin via OpenTimestamps. This distinguishes it from sibling tools like brain_get_notarization_proof (retrieval) or brain_list_notarizations (listing).

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

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

The description specifies it is an operator-only background task and notes the Bitcoin confirmation delay (1-6 hours), providing clear context for appropriate use. However, it does not explicitly state when not to use it or list alternatives.

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