taxsort-mcp

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

With no annotations, the description carries full burden. It discloses the free operation, no credit consumption, the need for dpop_token authentication, and detailed requirements for the token (event kind, tag, expiration). It does not mention rate limits or side effects, but for a read-only statement tool this is adequate.

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

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

The description is well-structured with a clear lead sentence followed by details and an explicit Args section. Every sentence adds value, though the dpop_token explanation is somewhat lengthy. It is front-loaded with the core purpose.

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

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

Given the tool has 3 parameters, no annotations, and an output schema exists (so return values don't need elaboration), the description covers all needed aspects: purpose, free nature, auth requirements, and parameter details. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 0%, so the description must compensate. It thoroughly explains npub (patron's Nostr public key), dpop_token (raw JSON event with specific constraints), and days (default 30, number of days of history). This adds significant meaning beyond the bare schema types.

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, lists what it includes (purchase history, credit tranches, usage breakdown, daily logs), and distinguishes it from the operator's Authority tax balance. The verb 'Generate' and resource 'account statement' make 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 explicit usage context: it is free, requires proof of npub ownership, and specifies the dpop_token format. It implicitly tells when to use (to get a patron's statement) but does not explicitly contrast with sibling tools like taxsort_get_transactions or taxsort_get_summary. Still, the guidance is strong.

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

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

With no annotations provided, the description carries the full burden. It discloses the cost (1 api_sat per call), authentication verification via `debit_or_deny`, output format (dark-themed SVG), and detailed dpop_token requirements. It does not mention potential error states or rate limits, but the provided information is substantial and adds value.

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

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

The description is well-structured with a clear purpose statement followed by a bullet-like argument list. It is not overly verbose, though the dpop_token explanation is detailed but necessary. Every sentence adds value, making it appropriately sized for the complexity.

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

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

Given the presence of an output schema (though not provided) and the lack of annotations, the description covers input parameters thoroughly, mentions output format and content (balance hero, metrics cards, etc.), relates to sibling tool, and includes cost. It is sufficiently complete for an agent to understand what the tool does and how to invoke it.

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

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

Schema coverage is 0%, so the description must fully explain parameters. It does so excellently: `npub` is clearly described, `dpop_token` has a thorough explanation with format and constraints, and `days` is explained with default value. This adds significant meaning beyond the schema.

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

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

The description clearly states that the tool generates a visual SVG infographic of an account statement. It distinguishes itself from the sibling tool `taxsort_account_statement` by noting that it returns the same data but rendered as a graphic, making it specific and differentiated.

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

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

The description implies when to use this tool (when a visual infographic is desired) and contrasts with the sibling `taxsort_account_statement`, which returns raw data. However, it does not explicitly state when not to use it or provide exclusions for other tools, though the context is clear.

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

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

With no annotations, the description adds 'Free' and 'Polls the Authority MCP-to-MCP', which are helpful but lacks details on errors, rate limits, or data freshness. Adequate but not fully transparent.

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

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

Three short sentences, front-loaded with the core purpose. No extraneous text; every sentence earns its place.

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

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

For a simple status check with output schema available, the description is largely complete. Could mention the output format briefly, but not a major gap.

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

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

The description mentions 'chosen Authority' hinting at authority_npub, but does not explain either parameter (dpop_token or authority_npub) explicitly. Schema coverage is 0%, so description fails to compensate.

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

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

The description clearly states the action ('Check') and the resource ('adoption-request status'), specifies the target ('at a chosen Authority'), and lists possible statuses. This distinguishes it from siblings like request_adoption.

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

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

The description explains the tool polls the Authority for status, giving clear usage context. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does not mention destructive potential, idempotency, error states, or what happens to the input data. The existence of an output schema is not leveraged to describe return values.

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

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

The description is a single, front-loaded sentence with no fluff. It efficiently communicates the core action and scope.

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

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

Given that an output schema exists, the description should explain what the tool returns or accomplishes beyond the input. It omits information about the outcome (e.g., number of transactions affected, errors). Mutation behavior and session state changes are unclear.

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

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

Only 33% of schema parameters have descriptions in the schema (npub), and the tool description adds no additional meaning. session_id lacks description, and dpop_token is empty. The description does not explain how parameters relate to the action.

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

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

The description clearly specifies the action ('apply rules'), the target ('unclassified transactions'), and the context ('in a session'). It distinguishes the tool from siblings like taxsort_save_rule and taxsort_get_rules by focusing on applying existing rules.

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, prerequisites (e.g., having a session and rules), or when not to use it. The description lacks context about workflow ordering.

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

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

No annotations are provided, and the description is too minimal. It does not disclose behavioral traits such as authentication requirements (e.g., npub for billing), response behavior, 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?

Description is concise with one sentence, but it is appropriately short. However, it lacks necessary detail to be fully useful.

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

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

Given 5 parameters and an output schema, the description is incomplete. It does not cover parameter roles, the nature of the advisor interaction, or output expectations.

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

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

Schema coverage is low (20%), and the description adds no meaning beyond the schema. Parameters like npub, history, dpop_token, and session_id 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?

Description clearly states the tool is for asking the Financial Advisor about TaxSort. However, it does not differentiate from the sibling tool taxsort_ask_tax_researcher, which likely serves a similar purpose.

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

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

No guidance on when to use this tool versus alternatives, no when-not scenarios, and no prerequisites or context provided.

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

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

No annotations are provided, and the description does not disclose any behavioral traits such as whether it is read-only, if it incurs costs, or has rate limits. The description is too minimal to inform the agent of side effects or constraints.

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

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

The description is a single sentence that concisely states the tool's purpose. It is front-loaded but could be more informative without losing conciseness.

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

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

Despite having an output schema, the description lacks details on how results are returned or what to expect. Given the tool's complexity, more context is needed for the agent to use it effectively.

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

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

Only 20% of parameters have descriptions in the schema. The description adds no extra meaning beyond the schema; it does not explain how to use the parameters or their semantics.

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 asks a tax code researcher about IRS provisions. It uses a specific verb-resource combination but does not differentiate from sibling tools like taxsort_ask_advisor.

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. Does not mention prerequisites, context, or scenarios for use.

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

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

With no annotations, the description carries full burden. It declares a read-only check, explains return value (sats available), and notes the financial consequence of zero balance. Could mention idempotency or lack of side effects, but sufficient.

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

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

Five sentences, front-loaded with purpose, then return value and workflow implications. No unnecessary words.

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

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

Complete for a parameterless check tool: explains what it returns, why it matters, and what action to take next. Output schema provides additional detail, but description stands alone.

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

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

No parameters exist, and schema coverage is 100%. Description adds no parameter detail, which is acceptable. Baseline 4.

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

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

Clearly states it checks the operator's tax balance at the Authority and distinguishes it as the operator's own funding, not a patron balance. Distinguishes from sibling tools like check_balance and purchase_credits.

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

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

Implies when to use (before certifying patron credit purchases) and what to do when balance is zero (call purchase_credits). Does not explicitly list when not to use, 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?

Discloses that the operation is free and requires proof of npub ownership to prevent enumeration. Describes dpop_token format in detail. Lacks explicit statement about being read-only or idempotent, but context implies it. With no annotations, this is strong coverage.

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

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

Concise (~150 words), front-loaded with core purpose, then sibling differentiation, then cost and proof requirements, then parameter details. No redundant sentences. Well-organized.

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

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

Given only two required parameters and an existing output schema, the description covers purpose, usage context, authentication, and parameter details thoroughly. No gaps.

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

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

Input schema has zero description coverage, but the description compensates fully: explains npub meaning (Nostr public key) and dpop_token format (kind-27235 event specs) with specific constraints, adding significant value 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 action ('check a patron's credit balance') and the resource (patron's balance at this operator). Distinguishes from sibling tool authority_check_balance by specifying its use for operator's own balance.

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

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

Explicitly states when to use (to check patron's spending balance) and when not to (for authority balance, use authority_check_balance). Also provides prerequisites: proof of npub ownership and that it's free.

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 fully handles behavioral disclosure. It explains the dpop_token requirements in detail (kind-27235, u tag with exact tool name, created_at within 60s, random nonce), mentions the purpose of preventing front-running, and states no cost. This is 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?

The description is well-structured with a clear purpose followed by usage context and parameter details. While it is somewhat lengthy due to the dpop_token explanation, every sentence adds necessary value for a tool requiring a complex authentication token.

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 (dpop token, Nostr proof, no annotations) and the presence of an output schema, the description covers all necessary context: usage flow, prerequisites, parameter meanings, and behavioral constraints. No gaps remain.

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

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

Schema coverage is 0%, but the description adds complete meaning for all three parameters: invoice_id is from purchase_credits, npub is the purchasing public key, and dpop_token has a detailed format specification. This fully compensates for the lack of schema documentation.

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

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

The description clearly states the tool checks the payment status of a Lightning invoice, with specific usage context ('Call after paying the invoice from purchase_credits'). It distinguishes itself from siblings like taxsort_check_balance and taxsort_check_proof_status by focusing on invoice payment 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 states when to use ('after paying the invoice'), provides cost context ('Free — no credits required'), and details a prerequisite ('Proof of npub ownership is required'). This gives clear guidance on 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 provided, so the description carries full burden. It discloses that the tool is free and previews costs, implying it is non-destructive and read-only. However, it does not explicitly state side effects, authorization requirements, or error handling behavior. The description adds context beyond the input schema but lacks completeness.

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

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

The description is well-structured: a one-line summary, a brief explanation, then clear parameter descriptions with examples. Every sentence adds value, and there is no unnecessary repetition. It is efficient and easy to parse.

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

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

Given the tool's complexity (4 params, output schema exists), the description covers the main purpose and two key parameters well. However, it omits explanations for npub and dpop_token, and does not mention output format or error conditions. While the output schema exists, the missing parameter descriptions reduce 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 0%, so the description must compensate. It explains tool_id and tool_kwargs in detail, including examples and resolution logic. However, it does not explain npub and dpop_token (both with defaults). This leaves two out of four parameters undocumented, which is a gap for agent 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's purpose: 'Preview the effective cost of a tool call.' It specifies that it shows base cost and constraint effects (discounts, free trials, surge pricing). This is specific and distinguishes it from sibling tools like taxsort_get_pricing_model, which likely returns the pricing model itself.

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

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

The description mentions that it is free ('Free — no credits required'), which provides a usage guideline. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use cost preview vs. actual pricing model). No exclusions or when-not-to-use guidance 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?

The description explicitly states the tool is free, has no side effects, does not evict the cache or touch relays. Since no annotations are provided, the description fully bears the burden and does so comprehensively.

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

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

The description is concise and well-structured: begins with core purpose, provides behavioral context, and ends with a clear Args list. Every sentence adds value without redundancy.

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

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

Given the tool is simple, has no annotations, and has an output schema, the description covers all necessary behavioral and parameter information. The presence of an output schema means return details are not required in the description, making it 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?

With 0% schema description coverage, the description adds full meaning for both parameters: patron_npub is required and described as a npub1... string, dpop_token is required and linked to related tools. This fully compensates for lack of schema descriptions.

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

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

The description clearly states the tool checks if a dpop_token is valid, with a specific verb and resource. It distinguishes itself by explicitly mirroring check_oauth_status for the npub-proof flow, making its 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 explains when to use the tool ('before burning credits') and that it is free with no side effects. While it does not explicitly say when not to use it, the context is clear and alternative tools are implied. Slight improvement could be explicit exclusions.

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

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

No annotations are provided, so the description must cover behavioral traits. It only says 'check if valid' without indicating whether this is a read-only operation, what constitutes validity (e.g., signature check, format validation), or any side effects. This lack of clarity leaves the agent guessing about the tool's 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 short sentence, which is concise but lacks critical details. It does not waste words, but it also does not add enough value to justify its brevity. It could be expanded slightly without losing conciseness.

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

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

Given the presence of an output schema and siblings like 'taxsort_request_unlock', the description is incomplete. It does not explain the output (even though output schema exists, it still helps to give context), the expected format of the 'response', or how this tool fits into a workflow. The agent would need additional 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 only 33% (only 'npub' described). The description does not add any parameter meaning beyond 'response' and 'dpop_token' are used. With three parameters and no explanation of 'response' or 'dpop_token', the tool is nearly unusable without external knowledge.

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

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

The description clearly states the tool's purpose: 'Check if the unlock response is valid.' It specifies a verb ('check') and a resource ('unlock response validity'), and it implicitly distinguishes from the sibling 'taxsort_request_unlock' which would handle the request side.

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 or when not to. It does not mention that a prior call to 'taxsort_request_unlock' is needed to obtain a response, nor any prerequisites or output interpretation context. The description gives no usage context at all.

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

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

Describes the destructive action of deleting all transactions and classifications. With no annotations, the description carries full burden; it lacks details on irreversibility, authentication needs, or side effects.

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

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

Single sentence of 15 words, front-loaded with the core action and purpose. Every word is relevant and 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?

Lacks details on prerequisites (e.g., valid session), return values (despite output schema existing), and fails to describe two parameters. For a destructive tool with no annotations, this is insufficient.

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?

Description does not explain any of the three parameters. Schema description coverage is only 33% (npub has description), leaving two parameters (dpop_token, session_id) undocumented in both schema and 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?

Clearly states 'Delete all transactions and classifications for a session', specifying the verb and resource. Distinguishes from siblings like taxsort_delete_account_transactions and taxsort_delete_classification by targeting all session 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?

Explicitly mentions the use case 'so CSVs can be re-imported', guiding the agent on when to use this tool. Does not explicitly state when not to use or list 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 must fully disclose behavior. The phrase 'live preview' suggests no data mutation, but this is not explicitly stated. There is no mention of side effects, required permissions, or whether the operation is safe. An agent might infer read-only, but the lack of certainty is a gap.

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

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

The description is a single sentence, which is concise but omits important information. It earns its place in brevity but sacrifices completeness. The structure is front-loaded with the key action, but could be extended to cover essentials.

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 parameter richness (6 params, 2 required) and low schema coverage, the description is under-informative. It does not reference the output schema or explain the return value. The 'live preview' and rule pattern hint are helpful but insufficient for an agent to confidently invoke the tool.

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

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

Schema description coverage is only 17% (only npub is described). The description adds no parameter details beyond mentioning 'rule pattern', which corresponds to description_pattern. Critical parameters like session_id, amount_value, and amount_operator are unexplained. The description does not compensate for the sparse 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 'count' and the resource 'transactions matching a rule pattern', and adds 'live preview' to indicate it's non-binding. This distinguishes it from sibling tools like taxsort_apply_rules (which modifies data) and taxsort_get_rules (which lists rules). However, it could more explicitly contrast with similar counting tools if any exist.

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 versus alternative tools such as taxsort_save_rule (to save rules) or taxsort_apply_rules (to execute rules). The 'live preview' hint is the only usage hint, but it's implicit. No when-not-to-use or prerequisite context 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 provided; description does not mention side effects, authentication requirements, or that npub is needed (though schema suggests it). Limited 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?

Single sentence, no waste. However, lacks essential details; could benefit from elaboration.

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 6 parameters and 1 required, the description is too minimal. Missing when to use, behavior, output handling (output schema exists but not mentioned).

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

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

Schema description coverage is only 17% (only npub has a description). Tool description does not explain any parameters beyond the general purpose. Inconsistency between npub being described as 'Required' in schema property but not in top-level required array.

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

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

Description clearly states the tool creates GitHub issues for bugs, features, or feedback. However, sibling tool 'taxsort_report_issue' likely overlaps, and no differentiation is provided.

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 'taxsort_report_issue' or when not to use it. Missing context for selection.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as side effects, authentication requirements, or what happens upon creation. The description is too minimal to be informative.

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

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

The description is a single 9-word sentence, which is concise but overly minimal. It lacks structure such as bullet points or sub-sections, and could include more detail without becoming verbose.

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

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

Given the complexity (4 parameters, no annotations, low schema coverage, many siblings), the description is incomplete. It does not explain the return value, when to use, or what a session is, and does not leverage the existence of 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 only 25% (only 'npub' has a description). The tool description adds no additional meaning to parameters beyond the schema, failing to compensate for the low coverage.

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

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

The description clearly states 'Create a new TaxSort session for a tax year,' providing a specific verb and resource. It distinguishes from siblings like 'get_session' and 'list_sessions' that retrieve or list sessions.

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 'taxsort_get_session' or 'taxsort_list_sessions'. No prerequisites, context, or exclusions are mentioned, leaving the agent without direction among 40+ 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?

With no annotations, the description must fully convey behavioral traits. It only states that a token is created, but does not disclose side effects (e.g., whether it modifies the session, costs credits, or has rate limits). The agent cannot infer safety or mutability beyond the act of creation.

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

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

The description is a single concise sentence with no unnecessary words. However, it may be too terse to be fully useful, borderline under-specification.

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 (which could describe return values), the description omits critical context like required session existence, token lifetime behavior, or whether the token can be revoked. With no annotations, this is insufficient for a sensitive sharing 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?

Only 25% of parameters are described in schema (npub has a description), and the tool description adds no parameter details. It mentions 'this session' implicitly for session_id, but fails to explain 'dpop_token' or 'expires_days'. Given low schema coverage, the description should compensate but does not.

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

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

The description clearly states the action ('Create'), the object ('share token'), and the purpose ('so another user can access this session'). It is specific and distinguishes itself from sibling tools like 'taxsort_load_share_token' (load vs. create) and 'taxsort_create_session' (session vs. 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., an existing session), or any context such as the requirement for an npub for billing. The agent is left without direction on appropriate 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?

The description indicates a destructive action (delete all data), but with no annotations provided, it lacks detail on irreversibility, required authentication, or potential side effects. The behavioral disclosure is 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, concise sentence that communicates the core function efficiently 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 existence of sibling tool taxsort_clear_transactions, the description lacks contextual completeness by not explaining the difference. Also, it does not clarify the effect on the account or subsequent operations.

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

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

Schema description coverage is only 25% (only 'npub' has a description). The description adds no additional meaning beyond the schema parameter names, which are somewhat self-explanatory but insufficient.

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 'all transactions and classifications for a specific imported account'. However, it does not distinguish from sibling tools like taxsort_clear_transactions, which may have similar intent.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.

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

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

With no annotations, the description effectively discloses the primary behavioral effect: removing a classification reverts the transaction to unclassified. This is sufficient for a simple deletion action, though it does not mention if the operation is reversible or if multiple classifications can be removed at once.

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

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

The description is a single concise sentence that immediately conveys the primary action and effect. However, it could be slightly expanded to include usage 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?

Given the tool's simplicity and the presence of an output schema, the description is minimally viable. It states what the tool does but lacks guidance on when to use it or how it differs from similar tools, leaving the agent to infer from the name alone.

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

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

Schema description coverage is only 25% (only npub has a description). The tool description adds no information about any of the four parameters, leaving session_id and transaction_id entirely undocumented despite being required. This is inadequate for low coverage.

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

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

The description clearly states the action 'Remove a classification' and the effect 'reverting the transaction to unclassified', which distinguishes it from sibling tools like taxsort_save_classifications or taxsort_reset_classifications that have different purposes.

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

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

No guidance is provided on when to use this tool versus alternatives like taxsort_reset_classifications or taxsort_clear_transactions. The description does not mention any prerequisites or context for use.

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

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

With no annotations, the description discloses key behaviors: cascading to patron redemptions, no-op effect on chain steps referencing the deleted coupon, and the Studio surfacing warnings. The 'requires proof' detail is vague, but overall it provides substantial operational context beyond a bare delete operation.

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

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

The description is four sentences, front-loaded with the primary action, then detailing effects and restrictions. Every sentence provides unique information with no redundancy or filler.

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

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

Given the tool's destructive nature and side effects, the description covers cascades, no-op behavior, and access restrictions. However, it omits parameter explanations and does not describe what the output schema contains (e.g., deletion count, error), leaving some gaps for an agent to handle correctly.

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

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

The input schema has 0% description coverage, yet the description adds no explanation for either parameter (coupon_id or dpop_token). The description fails to clarify what coupon_id expects (e.g., format, lifecycle) or the purpose of dpop_token, 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 clearly states 'Delete a coupon,' specifying the exact action and resource. It distinguishes this deletion tool from related siblings like taxsort_mint_coupon or taxsort_forget_coupon by detailing the cascading effect on redemptions and the no-op behavior for references.

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

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

The description notes 'RESTRICTED to operator — requires proof,' indicating a usage constraint. However, it does not explicitly state when to use this tool versus alternatives like taxsort_forget_coupon, nor does it describe prerequisites or conditions for safe 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 and minimal description, the description fails to disclose side effects, required permissions, or that the operation is destructive and likely irreversible.

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 terse (4 words) and lacks necessary detail, making it under-specified rather than efficiently 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?

The description is insufficient given the tool has three parameters (one required) and is a destructive operation; it provides no context about return values, errors, or workflow.

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

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

The description does not mention any parameters, and the schema coverage is only 33%, leaving two parameters (dpop_token, category_id) undocumented in both schema and description.

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

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

The description clearly states the verb 'Delete' and the specific resource 'custom category', but does not differentiate this from sibling tools like delete_classification or delete_coupon.

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

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

No guidance on when to use this tool versus alternatives, such as other delete tools, nor any prerequisites or conditions.

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

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

Discloses that this is a write operation to sensitive vault, requires ownership proof via dpop_token, and is free. With no annotations, the description adequately informs about behavioral traits, though it lacks mention of irreversibility 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?

Well-structured with a summary sentence and an Args section. The dpop_token detail is lengthy but necessary for correct usage. Could be slightly more concise, but overall clarity is not compromised.

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

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

Covers purpose, parameters, cost, and security requirements. Output schema exists, so return value documentation is not needed. Minor gaps like field existence behavior are acceptable given the complexity.

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

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

Schema coverage is 0%, but the description provides thorough explanations for all three parameters. The dpop_token parameter is described in depth including format, constraints, and recommendations, far exceeding schema's bare string type.

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 'Remove a single patron credential field', specifying verb and resource. Explicitly says 'without affecting other fields', distinguishing it from bulk delete tools like taxsort_forget_credentials.

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 like 'Proof of npub ownership is required' and 'Free', but does not explicitly mention when to use this tool versus alternatives (e.g., taxsort_forget_credentials for removing all fields). Implicit differentiation through scope, but no direct guidance.

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

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

No annotations provided, so description carries full burden. It does not disclose whether deletion is permanent, cascading, or requires authorization. For a deletion 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?

One sentence, efficient, with no wasted words. Front-loaded with the action and resource.

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 deletion operation with billing tokens (npub, dpop_token) and an output schema, the description is too minimal. It lacks context on success/failure, token usage, and any side effects.

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?

Of 3 parameters (npub, rule_id, dpop_token), only rule_id is implied by 'by ID'. npub and dpop_token are not explained. With only 33% schema coverage, the description should compensate but does not.

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

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

The description clearly states the verb 'delete' and resource 'classification rule' with the method 'by ID'. It distinguishes from sibling tools like save_rule and get_rules.

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

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

No guidance on when to use this tool vs alternatives (e.g., there is taxsort_save_rule for creating/updating). No mention of prerequisites like the rule existing or idempotency.

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

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

Discloses that the operation is cosmetic (non-destructive) and that the patron can re-redeem. However, it does not detail auth requirements beyond 'npub proof' or mention any side effects like rate limits or response format. Without annotations, the description carries full burden and is mostly transparent.

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

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

Three sentences, each serving a distinct purpose: action, behavioral caveat, and cost/requirement. Front-loaded with the verb, minimal waste.

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

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

Covers the action and behavioral nuance but omits parameter guidance and does not reference the output schema. While the output schema exists, the description should help the agent understand inputs, which it does not.

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

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

Schema description coverage is 0%, and the description does not explain what npub, coupon_id, or dpop_token mean. It mentions 'npub' in context but adds no semantic value for parameters, leaving the agent without guidance on how to fill them.

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

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

The description clearly states the action: 'Remove a coupon from this patron's redemption list.' This distinguishes it from siblings like taxsort_delete_coupon (permanent deletion) and taxsort_redeem_coupon (adding a 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?

Explicitly states it is 'cosmetic only' and that the coupon still exists and can be re-redeemed, guiding when to use this tool versus permanent deletion. Also mentions 'Free — requires proof of npub,' providing cost and prerequisite context.

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

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

No annotations provided, so description carries full burden. It discloses that deletion is as destructive as a write and requires proof of npub ownership. Also details dpop_token requirements (format, time constraint, tag constraints), offering excellent 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?

Description is relatively long but every sentence adds value. The parameter details are necessary. Could be slightly more concise, but structure is logical with a clear intro followed by parameter list.

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

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

Covers purpose, usage context, destructive nature, and parameter details thoroughly. Given an output schema exists, return values need no explanation. Could mention error behavior or idempotency, but overall complete for a destructive tool.

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

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

Schema coverage is 0%, so description must explain all parameters. It does so thoroughly: service and npub are described clearly, and dpop_token has a detailed explanation of format, constraints, and examples. This adds significant meaning beyond the bare schema.

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

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

Clearly states it deletes vaulted credentials for a specific service and npub. The verb 'forget' conveys deletion. While not explicitly distinguishing from siblings like 'delete_patron_credential', the description clarifies it handles both operator and patron credentials, which reduces 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?

Provides explicit context: use for operator credentials with operator's npub, for patron credentials with patron's npub, and notes destructive nature. Does not explicitly exclude scenarios or mention alternatives, but the context is sufficient for most cases.

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

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

With no annotations, the description carries the burden of behavioral transparency. It indicates a read operation ('list') and scoping ('in this session'), but does not disclose potential side effects, authorization needs, or pagination behavior. Adequate for a simple list tool.

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

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

The description is a single, concise sentence that directly conveys the tool's purpose. No extraneous information. Perfectly 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?

The description is complete for the tool's simplicity. It specifies the output scope (accounts with types and transaction counts) and the presence of an output schema covers return value details. No gaps given the tool's straightforward nature.

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

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

Schema coverage is only 33% (only npub has a description). The tool description adds no additional meaning to the parameters beyond what the schema provides. For instance, 'session_id' is required but its role is not explained. The description fails to compensate for the low schema coverage.

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

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

The description clearly states the action (list), resource (accounts), and scope (in this session with types and transaction counts). It effectively distinguishes from sibling tools like taxsort_get_transactions (lists transactions) or taxsort_get_summary (aggregated 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 implies when to use (when account-level information is needed) but provides no explicit guidance on when not to use or comparisons with alternatives. The context is clear but lacks 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 bear the full load. It states the core behavior (fetching neighbors) but omits details on auth requirements, rate limits, or state changes. The npub parameter's billing mention adds some transparency, but overall it lacks depth.

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

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

Two sentences, no extraneous words. The first sentence states the action, the second provides context. 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 is too brief for a tool with 7 parameters. It doesn't clarify the return format, pagination, or how exclude_id works. The duplicate detection use case adds value, but the description is not complete enough for an agent to use confidently.

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

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

The description adds meaning to amount, date, and days by explaining the neighbor logic, but with only 14% schema description coverage, it fails to explain the other four parameters (exclude_id, dpop_token, session_id, npub's role beyond billing). This is insufficient.

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 fetches transactions with the same amount within ±days of a date. It also gives a specific use case: duplicate detection from CSV imports, which distinguishes it from sibling tools like get_transactions.

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 mentions the tool is used by the classifier for duplicate detection. This provides context for when to use it, though it does not explicitly state when not to use it or name alternatives. Still, the guidance is clear enough.

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

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

Annotations are absent, so the description should disclose behavioral traits. It only states the tool gets a key, with no mention of whether it is read-only, authentication needs, rate limits, or consequences. This is insufficient for safe agent 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 a single sentence, making it concise. However, it is overly short for a tool with security implications and two parameters, lacking necessary context. It is adequately structured but insufficiently informative.

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

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

Given the tool has an output schema and no annotations, the description should provide context about why to get the key and what the response contains. It fails to do so, leaving critical gaps for an agent to use it correctly.

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

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

Schema description coverage is 50% (npub described, dpop_token not). The description does not add meaning beyond the schema; it fails to clarify dpop_token's purpose and contradicts the npub description's 'Required' label. The description should compensate but does not.

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

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

The description clearly states the tool gets the Anthropic API key for FE-driven classification, distinguishing it from similar tools like taxsort_get_github_token. However, it does not explicitly differentiate from other get_* tools, so it stops short of a 5.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use, or how to integrate with other tools. The npub parameter is described as 'required' in the schema description but is not marked as required in the schema, creating confusion.

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

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

With no annotations, the description must disclose behavioral traits but only states it's a read operation. Missing details on authentication needs, rate limits, data freshness, 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?

The description is very short (8 words), which is concise but sacrifices completeness. It lacks structure and additional context that would aid an AI agent.

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

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

Given the lack of annotations and minimal description, the tool is incomplete. An output schema exists but does not compensate for missing behavioral and usage context.

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

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

Schema description coverage is 33% (only npub described). The tool description adds no extra meaning for the parameters dpop_token and session_id, failing to compensate for the schema gaps.

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

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

The description clearly states the verb 'Get' and the resource 'aggregated API usage statistics' with a purpose 'for cost analysis', which distinguishes it from other 'get' tools like get_accounts or get_transactions.

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

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

No guidance on when to use this tool versus alternatives such as get_transactions or get_summary. The description lacks exclusions or context for 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 only states the basic action without disclosing traits like read-only nature, authentication requirements (npub is documented as required but not in description), rate limits, or whether pagination is needed. Minimal 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?

Extremely concise at one short sentence, which is efficient for a simple retrieval. However, it could benefit from slightly more structure (e.g., listing output or parameters) without sacrificing conciseness.

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

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

For a simple getter with an output schema, the description is minimally adequate but lacks context around parameter usage, output format, and error conditions. Given the sibling tool set and no annotations, more completeness would help agent decision-making.

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

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

The description adds no parameter-level detail beyond the schema. Schema coverage is 50% (only npub has a description), and dpop_token lacks any documentation. The description does not compensate for this gap, leaving the dpop_token purpose unclear.

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 ('custom categories') scoped to 'this user'. It effectively distinguishes this retrieval tool from sibling tools like taxsort_save_custom_category and taxsort_delete_custom_category.

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

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

No guidance on when to use this tool versus alternatives (e.g., when to list vs. get specific categories). No context about prerequisites, such as needing a valid npub or session, or expected behavior when no categories exist.

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

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

No annotations provided, description only states a read operation. Does not disclose behavior like rate limits, authentication requirements, or side effects. Minimal 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?

Single sentence, front-loaded and to the point. Could add more detail without becoming verbose.

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

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

Given two parameters and an output schema (not shown), the description lacks context on how the token is returned, the role of npub and dpop_token, and any required sequence. Incomplete for reliable agent use.

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

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

Description does not explain the parameters; schema covers npub with description but dpop_token has none (50% coverage). Tool description adds no semantic value 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 verb 'Get', resource 'GitHub token', and purpose 'for creating issues in the taxsort-mcp repo'. Distinguishes from sibling tools like taxsort_get_anthropic_key.

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 taxsort_get_anthropic_key. No prerequisites or when-not-to-use 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 provided; the description does not disclose behavioral traits such as safety, destructiveness, authentication needs, or rate limits, nor does it explain what 'statistics' entails.

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

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

A single sentence clearly states the purpose. Efficient and front-loaded, though slightly too sparse for a tool with multiple parameters.

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

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

Despite having an output schema, the description fails to explain what the statistics contain, the relationship to sessions, or any required preprocessing (e.g., session must exist). Inadequate 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 coverage is only 33% (npub has description), but dpop_token and session_id lack descriptions. The tool description adds no additional meaning beyond the schema for any parameter.

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

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

The description uses a specific verb ('Get') and resource ('import statistics') and clarifies scope ('for a session'), clearly distinguishing it from siblings like get_transactions or import_csv.

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

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

No guidance on when to use this tool versus alternatives (e.g., import_csv, get_transactions), nor any prerequisites or context about when a session is active.

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 fully reveals behavior: returns specific metadata fields or an empty profile if none exists. Since no annotations exist, this description carries the full burden and does so thoroughly.

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 defines the core action, second adds cost, authentication, and return details. Front-loaded and efficient.

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

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

Given the tool's simplicity (one optional param, no required fields, output schema exists), the description covers everything needed: the data source, public nature, return fields, and fallback 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?

With a single optional parameter and no schema description coverage, the description does not elaborate on the npub parameter beyond the tool name. However, the context makes it obvious; 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 'Read an npub's public Nostr profile (NIP-01 kind-0 metadata)', specifying the exact resource and action. It distinguishes from sibling tools like taxsort_publish_nostr_profile.

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

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

The description provides clear usage context: 'Free, no proof — the data is already public on relays.' This tells the agent no authentication is needed and it's safe to use, though it does not explicitly exclude other tools.

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

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

No annotations are provided, so the description must disclose all behavioral traits. It only states the function and arguments, omitting side effects (likely read-only), authentication requirements, error conditions, or idempotency. The user cannot infer whether this operation is safe or has 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: a single sentence defining the core functionality, followed by a clear Args list. No unnecessary words, and the most important information is front-loaded.

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

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

Given the tool's simplicity and the presence of an output schema (though not shown), the description covers the essential inputs and purpose. However, it lacks workflow context, such as when to use this tool (e.g., after notarization) and what the output proof is used for. It is minimally complete but not rich.

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

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

Parameter descriptions are provided via the Args section, adding meaning beyond the basic schema types (both strings). 'notarization_id' is explained as 'The notarization record ID' and 'npub' as 'The patron's Nostr public key (npub1...)', which clarifies the expected format. Schema coverage is 0%, so the description compensates well.

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. The verb 'Generate' and specific resource 'Merkle inclusion proof' make the purpose unambiguous and differentiate it from sibling tools like list_notarizations or check_proof_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 does not provide any guidance on when to use this tool versus alternatives. It lacks context such as prerequisites (e.g., notarization must exist) or scenarios where other tools (like check_proof_status) are more appropriate.

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

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

Although no annotations are provided, the description implies a read-only operation (reporting readiness) with no side effects. It adds the note 'Free', possibly indicating no cost, but does not detail other behavioral aspects like rate limits or data source.

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

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

The description is extremely concise at three short sentences. It front-loads the purpose, then enumeration, then alternative usage. Every sentence adds value with no redundancy.

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

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

Given no parameters and an output schema present, the description adequately covers the tool's functionality. It specifies what the output indicates (settings configured/missing and delivery instructions) but could be slightly more explicit about the scope of 'operator settings'.

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

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

The tool has zero parameters, so per the guidelines the baseline is 4. The description does not need to add parameter details since there are none.

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

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

The description clearly states the tool's purpose: 'Report this operator's configuration readiness.' It specifies what it shows (configured, missing, how to deliver missing values) and explicitly distinguishes from the sibling tool 'get_patron_onboarding_status'.

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

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

The description explicitly tells the agent when to use an alternative tool ('For patron-level credential status, use get_patron_onboarding_status instead'), providing clear guidance on tool selection.

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

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

Despite no annotations, the description thoroughly discloses behavior: it never exposes values, returns delivered_at timestamps (nullable), and states that the list itself is sensitive. It also details the authentication requirement and provides specific instructions for the dpop_token format. However, it doesn't discuss error handling or edge cases, hence a 4 instead of 5.

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

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

The description is well-structured with a concise first sentence followed by a detailed paragraph and parameter breakdown. While it is somewhat lengthy, every sentence contributes value (e.g., timestamp behavior, security notes). A slightly tighter edit could remove redundancy (e.g., 'Proof of npub ownership is required' is mentioned twice), but overall it remains efficient.

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

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

Given the tool has an output schema (not shown), the description appropriately focuses on input and behavioral aspects. It covers purpose, parameter details, authentication, and security implications. The explanation of dpop_token is particularly thorough. No gaps are evident for an agent to invoke it correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: npub as the Nostr public key, and dpop_token as a raw JSON kind-27235 event with specific constraints (u tag, nonce, created_at within 60s). This adds critical meaning beyond the schema's empty property objects.

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

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

The description clearly states that the tool lists stored patron credential field names (not values), specifying that it returns names and null timestamps for vaulted fields. It differentiates itself by emphasizing that values are never exposed, setting it apart from sibling tools like taxsort_update_patron_credential or taxsort_delete_patron_credential that deal with credential values.

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

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

The description explicitly says to use this to verify which fields are configured and how old each one is. It also mentions the prerequisite of proof of npub ownership and that the list is free. While it doesn't explicitly state when not to use it, the tool's unique purpose among siblings makes the guidance clear and adequate.

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 covers important behavioral aspects: it is free, requires proof of npub ownership, and reports sensitive information. It implies a read-only operation ('Report'), but does not detail error cases or timeout 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 well-structured with a clear introductory sentence, a breakdown of behaviors, an 'Args' section, and no unnecessary words. It is concise yet comprehensive.

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

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

Given the presence of an output schema, the description need not detail return values. It covers purpose, behavior, authentication, and parameter details sufficiently for a read-only information tool.

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

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

The description provides full meaning for both parameters: 'patron_npub' is described as a Nostr public key with format hint, and 'dpop_token' is explained as a specific kind of signed event. This adds crucial context beyond the empty schema descriptions.

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

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

The description clearly states the tool reports a patron's credential readiness, distinguishing between set-once and OAuth2 services. The verb 'report' and resource 'patron onboarding status' are specific. It differentiates from the sibling 'get_operator_onboarding_status' by focusing on the patron.

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 ownership proof is required and that credential presence is sensitive, implying authentication context. It does not explicitly list when to use versus alternatives, but the purpose is clear enough to guide 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?

Description discloses a side effect (self-initializes a scaffold if no model exists) and clarifies no economic data comes from code. However, it does not state authentication requirements, idempotency, or potential constraints on 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?

Three concise sentences, front-loaded with the core purpose. No extraneous information.

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

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

For a zero-parameter tool with an output schema, the description covers the core functionality and side effect. Could mention that the output is a pricing model object if not evident from schema, but overall adequate.

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

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

There are no parameters, so baseline is 4. The description adds relevant context beyond the empty schema (e.g., self-initialization behavior).

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

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

The description clearly states the action ('Get') and the resource ('active pricing model for this operator'). It distinguishes from sibling tools like 'set' and 'reset'. Additional context about initialization adds clarity.

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

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

No guidance on when to use this tool versus alternatives (e.g., when to get vs set or reset). No exclusions or prerequisites 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. 'Get' implies a read operation, but the description does not clarify any behavioral traits such as read-only status, side effects, authentication requirements, or what happens if no rules exist. The agent is left to assume safe behavior without confirmation.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every word is essential: verb, resource, scope. It is perfectly concise for a simple retrieval 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?

Although an output schema exists (so return format is covered), the description lacks essential context: what constitutes a 'classification rule', how the 'current patron' is identified, and how this tool relates to other rule-related tools. Given the tool complexity and sibling count, the description is incomplete for safe agent use.

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

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

Schema description coverage is only 33% (only npub has a description). The tool description adds no meaning to any of the three parameters—it does not explain npub, dpop_token, or session_id or how they affect results. An agent must rely solely on the schema, which has sparse descriptions and defaults.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('all classification rules') with a scope ('for the current patron'). It distinguishes this tool from siblings like taxsort_save_rule, taxsort_delete_rule, and taxsort_apply_rules, which involve modifying or applying rules instead of just retrieving them.

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

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

The description provides no guidance on when to use this tool versus alternatives. Given 79 sibling tools, many of which also operate on rules (e.g., taxsort_count_rule_matches, taxsort_get_custom_categories), an agent would not know when retrieval is appropriate or what prerequisites exist. No when-not-to-use or alternative tool mentions.

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

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

No annotations are provided, and the description does not disclose behavioral traits like side effects, authentication requirements, or rate limits. The word 'get' implies a read operation, but this is not explicitly stated.

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 (one sentence), but it lacks front-loading of critical information and could be better structured to include usage context or parameter hints.

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 existence of an output schema helps document return values, but given the number of sibling tools and absence of usage guidelines, the description is not sufficiently complete for an agent to decide when to invoke this tool.

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

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

The input schema has three parameters, but only 'npub' has a description in the schema. The description adds no additional meaning to any parameter, and with only 33% schema coverage, the description fails to compensate for the lack of parameter documentation.

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

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

The description states the tool gets session details and summary stats, clearly indicating the verb and resource. However, it does not differentiate from siblings like taxsort_get_summary or taxsort_session_status, which could also retrieve session-related information.

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 taxsort_list_sessions or taxsort_session_heartbeat. There is no mention of 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?

With no annotations provided, the description must fully disclose behavioral traits, but it only states the basic purpose. It does not mention whether the tool is read-only, any side effects, authentication requirements beyond the required session_id, or potential rate limits.

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

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

The description is very concise (8 words) but lacks structure and essential details. While brevity is valued, it sacrifices clarity and completeness.

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 6 parameters with minimal schema coverage, no annotations, and an output schema, the description is incomplete. It fails to explain what the summary contains, how grouping works, or the intended use for tax reporting, leaving the user uninformed.

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 very low (17%, only npub described). The tool description adds no parameter information, leaving five parameters (month, scope, group_by, dpop_token, session_id) unexplained. This severely hinders 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 the tool retrieves a grouped spending summary for tax reporting, which is distinct from raw transaction retrieval. However, it lacks specificity about what grouping means and how it differs from similar 'get' tools like taxsort_get_transactions.

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 over siblings. The description does not mention any prerequisites, context, or alternative tools for different use cases.

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

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

No annotations are provided, so the description must disclose behavioral details. It mentions a LEFT JOIN with classifications but omits rate limits, auth requirements, or any side effects. For a read operation, it is minimally transparent but insufficient for a tool with 13 parameters.

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

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

The description is three sentences, front-loaded with purpose, and every sentence adds value. No redundant or filler content.

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

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

Despite having an output schema, the description fails to cover most of the 13 parameters or provide usage context for common filters. The presence of a sibling tool for paged transactions suggests additional guidance is needed, which is missing.

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

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

Schema description coverage is only 8% (only npub has a schema description). The description adds meaning to session_id, unclassified_only, date_from, and date_to, covering only 4 of 13 parameters. Many parameters like limit, offset, search, category are left undocumented, inadequately compensating for the low schema coverage.

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

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

The description clearly states 'Get transactions for a session with optional filters', which provides a specific verb and resource. However, it does not differentiate from the sibling tool 'taxsort_get_transactions_paged' which presumably handles pagination differently.

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 advises when to use unclassified_only and date_from/date_to, but lacks guidance on when not to use this tool or when to prefer alternatives like taxsort_get_transactions_paged. No explicit exclusions are given.

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

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

With no annotations, the description must disclose all behavioral traits. It explains the internal sorting/grouping logic (group_sort, sort_col, sort_dir, group_by interaction) which is valuable. However, it omits details about pagination behavior, rate limits, side effects, or the fact that npub is used for credit billing (only in schema's parameter description for npub). The description adds moderate transparency beyond the schema 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?

The description is very concise with only 3 sentences. The first sentence provides a high-level summary, followed by specific details on sorting/grouping. No unnecessary words; each sentence adds value. It is well front-loaded.

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

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

Given the tool's complexity (16 parameters, output schema exists), the description is incomplete. It fails to explain pagination mechanics, filtering parameters, billing (npub), and many other options. While the output schema may cover return structure, the description should at least cross-reference key parameters. A user would struggle to use this tool correctly without additional 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 description coverage is only 6% (only npub has a description). The description adds meaning for only 3 parameters (group_sort, sort_col, sort_dir) out of 16, neglecting many important ones like page, page_size, search, filters, etc. Given the low schema coverage, the description should have explained more parameters to aid correct usage.

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

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

The description clearly states 'Server-side filtered, grouped, sorted, paginated transactions', which defines the core purpose. However, it does not distinguish this tool from the sibling 'taxsort_get_transactions', which likely provides simpler transaction retrieval. The explanation of sorting/grouping behavior adds clarity but misses a direct contrast.

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

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

No explicit guidelines on when to use this tool versus alternatives like 'taxsort_get_transactions'. The description assumes the user knows when pagination or grouping is needed, providing no situational context or prerequisites beyond the required session_id.

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

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

No annotations are provided, so the description must cover behavioral traits. It describes input format but fails to disclose side effects (e.g., appending vs replacing data), required permissions, error handling, or billing implications (e.g., npub parameter).

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, using one sentence plus a brief note. It is appropriately front-loaded with the main purpose. Could be slightly more structured but efficient.

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

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

Given 6 parameters (3 required) and no annotations, the description is incomplete. It does not explain the overall workflow (e.g., need a session, what happens with the imported data) or return value (though output schema exists).

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

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

Schema description coverage is only 17% (npub only). The description adds meaning to 'content' (raw CSV text) and 'account_name' (overrides filename-derived account) but leaves other parameters like session_id and dpop_token unexplained. It partially compensates for low schema coverage.

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

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

The description clearly states the action ('Import a CSV file') and the target ('into a session'). It is specific and distinguishes from other tools like taxsort_create_session or taxsort_get_transactions.

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 minimal guidance on when to use this tool. It mentions optional account_name override but does not specify prerequisites (e.g., session must exist) or alternatives. No explicit when-not-to-use conditions.

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

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

Despite no annotations, the description thoroughly discloses behavior: it's free with no side effects, includes ToolIdentity-seeded tools plus @paid_tool UUIDs missing from registry (flagged registered:false), exposes unregistered tools in a top-level array for drift detection, and explains the canonical-UUID design including rename/rebrand behavior. This richly compensates for the absence of annotations.

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

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

The description is well-structured with clear paragraphs delineating the output, the authoritative-source rationale, drift detection, and the canonical-UUID design point. It's slightly verbose—the rename/rebrand paragraph and repeated drift-detection theme—but every section earns its place given the complexity of the tool's guarantees.

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

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

For a zero-parameter introspection tool with an output schema, the description is thorough: it explains the full output semantics, the drift-detection purpose with issue references, the authoritative-source positioning, and side-effect safety. It completely covers what an agent needs to know to select and interpret this tool.

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

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

The tool has 0 parameters and 100% schema coverage, so the schema leaves nothing undocumented. The description goes beyond schema by explaining the output shape (registered:false flag, unregistered array) and the design semantics around tool_id stability versus mcp_name changes, which is meaningful behavioral context for a parameterless tool.

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 returns canonical tool identities (tool_id, mcp_name, etc.) for every tool the wheel exposes. It explicitly differentiates this from name-based derivation and identifies the authoritative use case for Reconcile. Distinct from all 90+ sibling tools.

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

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

The description specifies this is the authoritative source for 'Studio, agents, FE' that need to know how the MCP identifies its tools, and explains it's used by Reconcile for UUID-join against the pricing model. Clear context on when to use, though it doesn't name explicit alternatives/exclusions since this is a unique system-level tool.

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

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

No annotations are provided, so the description carries the full burden. It describes the return fields and cost, which is sufficient for a simple read-only listing. No contradictions.

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

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

The description is concise with three sentences, each adding value: purpose, return fields, and cost. 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 no parameters and the existence of an output schema, the description is mostly complete. It explains what is returned and that it is free. Slightly more context on potential limitations could elevate it.

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

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

The input schema has zero parameters, so baseline 4 applies. The description does not need to add parameter information as none exist.

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, specifying the verb 'list' and the resource. It distinguishes itself from sibling tools which focus on 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?

The description provides context such as 'Free — no credits required' and what is returned, but 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?

Describes the output includes times_redeemed and total_uses, and mentions the sorting order. No annotations exist, so the description adequately conveys it is a read-only list with authentication requirements.

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

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

Three sentences: purpose with ordering, key field detail, and access restriction. No redundant information; each sentence adds necessary 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?

Covers core behavior and a specific field, and notes restriction. However, it omits pagination details and does not explain the dpop_token parameter. The presence of an output schema mitigates the need for return value details.

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

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

The only parameter, dpop_token, is not explained in the description. With 0% schema description coverage, the agent must infer its purpose (likely for authentication) from context clues like 'requires proof'.

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

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

Clearly states the tool lists every coupon minted by the operator, sorted newest first. Differentiates from related tools by specifying operator scope and restriction, but does not explicitly contrast with sibling taxsort_list_my_coupons.

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

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

Notes the tool is restricted to operators requiring proof, indicating when to use. However, it does not provide explicit guidance on when not to use or mention alternative tools for non-operator users.

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

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

No annotations are provided, so the description must fully disclose behavior. It only states the tool lists feedback issues, with no mention of read-only nature, side effects, pagination, filtering, or output contents. This is insufficient for a safe and correct invocation.

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

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

The description is a single concise sentence with no unnecessary words. However, its brevity sacrifices clarity and completeness; a slightly longer description could improve utility without losing conciseness.

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

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

The description is incomplete given the tool's complexity. It lacks information about output schema, default behavior, filtering, sorting, or authentication context. Despite an output schema existing, the description does not mention return values, leaving the agent uncertain about what to expect.

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

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

Schema coverage is 50% (only npub has a description), but the tool description adds no parameter-specific information beyond what the schema already provides. The dpop_token parameter is entirely undocumented in both schema and description, and the purpose of npub beyond 'credit billing' is unclear.

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

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

The description clearly states the action (list) and resource (feedback issues) and specifies the scope (by this patron). It distinguishes the tool from siblings like taxsort_create_feedback_issue, but does not explicitly differentiate from other list tools or clarify identification of 'this patron'.

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

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

No guidance on when to use this tool versus alternatives such as taxsort_report_issue or taxsort_create_feedback_issue. The description lacks context about prerequisites, authentication, or exclusions.

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

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

With no annotations, the description carries full burden. It discloses the tool returns both active and exhausted redemptions with a status field, and mentions it is free but requires proof of npub. This provides good insight into the tool's behavior without contradictions.

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

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

The description is three sentences, each serving a clear purpose: stating the function, detailing output, and noting prerequisites. It is concise but could be more structured with bullet points for readability.

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

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

Given the low complexity of a list tool and the presence of an output schema, the description covers the essential aspects: what it lists, the status field, and the proof requirement. It does not mention pagination or limits, but these are less critical for a simple listing.

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 mentions 'npub' proof, adding context that the npub parameter is a proof identifier. However, it does not explain the dpop_token parameter or the format of npub, leaving gaps.

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

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

The description uses the specific verb 'list' and identifies the resource as 'coupons this patron has redeemed on this operator', distinguishing it from sibling tools like taxsort_list_coupons which likely lists all coupons. The detail about return statuses adds clarity.

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

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

The description clearly states it lists redeemed coupons for a patron and mentions the requirement of 'npub' proof. It provides context for when to use this tool, but does not explicitly exclude alternatives or compare with siblings like taxsort_list_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. Description fails to disclose behavioral traits such as read-only nature, idempotency, pagination, or default ordering. Only states 'list recent' without explaining scope or side effects.

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

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

Very concise and well-structured: one-line summary followed by parameter details under 'Args'. No redundant information.

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

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

Output schema exists, so return values are covered elsewhere. However, missing usage guidance and behavioral details (e.g., recency definition, ordering) make it incomplete for a simple list tool. Adequate but not exemplary.

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 0% parameter descriptions, so description must compensate. Explicitly explains 'limit' as max records and 'status' as optional filter with examples, adding value beyond schema types and defaults.

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

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

Clearly states verb 'list' and resource 'Bitcoin notarization records'. Distinct from sibling tools like taxsort_get_notarization_proof (retrieve specific proof) and taxsort_notarize_ledger (create).

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 vs alternatives. Does not mention prerequisites or when not to use. Minimal context for selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the operation is a listing, but does not mention that it is read-only, requires authentication (implied by npub), or whether results are paginated. This is insufficient for an unannotated tool.

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

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

The description is a single concise sentence with no waste. However, it is too brief and lacks critical details, missing the opportunity to add value beyond the schema. Conciseness should not come at the expense of completeness.

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 (per context), the description need not explain return values, but it still fails to provide essential context like the fact that npub is required for billing, the role of dpop_token, or any authentication requirements. The description is too short to be considered complete for this tool with multiple parameters and siblings.

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

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

Schema description coverage is 50% (only npub has a description). The tool description does not add any parameter information beyond the schema; notably, 'dpop_token' remains unexplained. The description also contradicts the schema by calling npub 'Required' when it has a default and no required flag. The description should compensates for the coverage gap but fails.

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

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

The description clearly states the action ('List'), resource ('all sessions'), and scope ('owned by the current patron'). It effectively distinguishes from sibling tools like 'taxsort_get_session' (singular) and 'taxsort_create_session' (creation).

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

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

No explicit when-to-use or when-not-to-use guidance is provided. Given many sibling tools related to sessions, the description should indicate that for a specific session one should use 'taxsort_get_session' or when to create sessions. The lack of such guidance leaves the agent without direction.

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

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

The description does not disclose behavioral traits beyond the action. It is unclear if 'load' implies a read-only operation, state changes, or authorization requirements. No annotations are provided to help.

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 extraneous information. Highly 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 an output schema existing, the description does not hint at return values or behavior after loading. For a tool with 3 parameters and a share token mechanism, more context is needed for effective agent usage.

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

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

With 33% schema description coverage, the description adds no parameter details. It does not explain the format or role of 'share_token' or 'dpop_token', relying solely on the schema which already partially describes 'npub'.

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

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

The description clearly states the verb 'Load' and the resource 'shared session via a share token', which is specific and distinct from creating or getting sessions. However, it does not explicitly differentiate from sibling tools like `taxsort_get_session` or `taxsort_create_session`.

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

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

No guidance on when to use this tool versus alternatives (e.g., `taxsort_get_session`). Missing context on prerequisites such as needing a valid share token or prior session creation.

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

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

Discloses key behaviors: creation, return of coupon row, operator restriction, auth method, and defaults for uses_per_patron and total_uses. Lacks details on idempotency or error cases, but acceptable for a creation tool with no annotations.

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

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

Single paragraph with Arg list, efficient but could benefit from bullet formatting. 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?

Covers purpose, all parameters, return value, and authentication. Output schema exists, so return description sufficient. Missing error handling details, but overall adequate for a creation tool.

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