taxsort-mcp

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses that the call is free, that proof of npub ownership is required via dpop_token, and why that proof exists (preventing statement-scraping). It implicitly signals a non-mutating read operation, though it does not cover rate limits or error behavior.

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

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

Three sentences carry all essential information: purpose and return contents up front, the tax-balance exclusion, then cost and auth caveats. There is no filler, and each sentence adds operational 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?

With an output schema present and all parameters fully documented in the schema, the description is sufficient to invoke the tool correctly. The only notable gap is that the closely named sibling taxsort_account_statement_infographic is not referenced, leaving the agent to infer which statement variant to 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 100%, and the dpop_token schema entry is already highly detailed about raw kind-27235 framing, time window, and nonce. The description adds no new parameter-level syntax, only rein orces the proof-of-ownership concept, so the baseline 3 is appropriate.

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

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

States a specific verb ('Generate') and resource ('a patron's account statement') and enumerates exactly what is returned: purchase history, active credit tranches, per-tool usage breakdown, and daily usage logs. It also explicitly distinguishes itself from the operator's Authority tax balance, separating it from related balance 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?

Provides clear context: this tool is for a patron's spending-account statement, and it explicitly says what it is not (the operator's Authority tax balance). It does not name alternative sibling tools or state when to prefer another statement/transaction tool, so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full burden and handles it well by disclosing the 1 api_sat cost per call and the debit_or_deny proof verification before cost is incurred. It also reveals the output composition including hero, metrics cards, health gauge, tranche table, and usage breakdown. It doesn't mention side effects or failure modes, but generation tools are reasonably covered.

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

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

The description is compact and front-loaded, starting with the core action and then efficiently covering the output format, cost, and proof verification. Every sentence contributes useful information and there is no redundant or filler content.

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

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

The description covers the tool's purpose, output format, costing, and authentication proof flow, and an output schema exists to define return values. It is nearly complete, though it could have been slightly more explicit about when an agent should prefer this over the plain account_statement tool.

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

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

Schema description coverage is 100%, so the schema already fully documents npub, dpop_token, and days. The description adds no additional parameter-level meaning beyond reiterating that it renders the same statement data, which is enough to maintain the baseline without needing further compensation.

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

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

The description states a specific verb and resource: generating a visual SVG infographic of an account statement. It also distinguishes this tool from the sibling taxsort_account_statement by noting it returns the same data rendered as a dark-themed SVG graphic, so an agent can tell them apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names taxsort_account_statement as the source of the same data and clarifies that this tool renders it as an SVG infographic. This gives clear context for choosing between raw data and visual presentation, though it does not explicitly spell out when not to use this tool or provide exclusion 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?

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?

With no annotations, the description carries the full burden and does disclose useful behavioral facts: the call is free ('Free — no credits required') and requires proof of npub ownership to prevent enumeration of balances. It does not state read-only or rate limits, but for a simple balance-check operation the main cost and auth behaviors are covered.

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

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

The description is compact and front-loaded: the first sentence states the core action, the second paragraph clarifies scope and distinguishes the sibling, the third adds cost and security rationale. Every sentence earns its place 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 the output schema exists and the input schema is fully documented, the description covers the essential decision context: what balance is checked, when to use this vs the alternative, that it is free, and the auth requirement. The one completeness gap is the misnamed alternative tool, which slightly weakens the disambiguation in a large sibling list.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions in the schema. The description adds context about the meaning of the balance and the proof requirement, but does not add anything about npub or dpop_token beyond what the schema provides. This meets the baseline for fully-covered parameters.

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

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

Description opens with a precise verb+resource: 'Check a patron's credit balance at this operator.' The second paragraph sharpens the scope by defining it as the patron's spending balance purchased via Lightning, and explicitly contrasts it with the operator's own Authority balance. This gives the agent a clear, unambiguous picture of what the tool does and how it differs from similar balance 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 gives an explicit when-to-use signal: for the patron's spending balance. It also names an alternative: 'use authority_check_balance instead' for the operator's Authority balance. However, the alternative name is inaccurate — the actual sibling is taxsort_check_authority_balance — so the routing instruction is explicit but slightly imprecise.

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

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

With no annotations provided, the description carries the full behavioral burden and delivers: cost behavior ('Free — no credits required'), an auth requirement ('Proof of npub ownership is required'), and the security rationale ('to prevent credit-grant front-running by an observer of the invoice ID'). This explains why the oddly strict dpop_token parameter exists, which is genuinely useful context. It doesn't disclose failure-mode behavior, but the disclosures present are substantial.

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

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

Four sentences, with purpose front-loaded first, then usage timing, cost, and auth rationale. Every sentence earns its place; the only minor waste is 'Free — no credits required,' which says the same thing twice. The structure is efficient and well-ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3-parameter tool, the description covers the full call context: what it does, when to call it (after purchase_credits), cost, and the auth prerequisite. Combined with 100% schema parameter coverage and an existing output schema, nothing essential for invoking it correctly is missing. The only gap is clarity on edge outcomes (e.g., unpaid/expired invoice behavior), which is minor.

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

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

Schema description coverage is 100%, so per the baseline rule the description needn't add parameter detail — and it doesn't. The schema itself already documents invoice_id's provenance (returned by purchase_credits), npub's format, and dpop_token's exact framing requirements. The description adds no new parameter semantics, so the baseline 3 is appropriate.

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

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

The first sentence uses a specific verb and resource: 'Check the payment status of a Lightning invoice.' Among many sibling check tools (check_balance, check_proof_status, check_unlock), this one is identifiable by its unique resource — Lightning invoice payment status. It stops short of 5 because it doesn't explicitly name a sibling it is not, and 'check' is a generic verb shared with several peers.

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

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

The description gives explicit temporal guidance: 'Call after paying the invoice from purchase_credits,' which anchors the tool in a clear workflow and ties it to a named sibling. It doesn't provide exclusions or state when not to use it vs other check_* tools, so it earns a 4 rather than a 5, but the when-to-use context is unambiguous.

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

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

With no annotations provided, the description must carry behavioral disclosure itself. It reveals that the tool is free and shows a cost breakdown, which is useful. However, it does not explicitly confirm that no side effects occur, whether authentication is needed via npub or dpop_token, or whether it actually executes the target call or merely estimates its cost.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and the second provides essential behavioral detail about cost and credits. Every sentence earns its place 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?

The output schema exists, so return-value documentation is not the description's job, and tool_id is well explained in the schema. Still, without annotations, the description omits side-effect clarity and leaves npub and dpop_token unexplained, so an agent may lack enough context for a fully correct call.

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

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

The description adds no parameter-level meaning. The schema covers tool_id and tool_kwargs, but npub and dpop_token are undocumented, and overall schema description coverage is only 50%. Since the description does not compensate for these gaps, parameter semantics are weakly supported.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Preview') and a clear resource ('the effective cost of a tool call'), then elaborates with what the preview shows: base cost and constraint effects like discounts, free trials, and surge pricing. This distinguishes it from sibling tools like get_pricing_model or check_balance, since the focus is on estimating an individual tool call's cost.

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

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

The description implies the tool is used to preview costs before making a tool call, and the 'Free — no credits required' note encourages safe use. However, it does not explicitly say when to prefer this over alternatives, nor does it state when not to use it or what prerequisites apply.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden and does so strongly: 'Free, no side effects — does not evict the cache or touch relays.' This tells an agent exactly what will and will not happen, beyond what the input schema can express.

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

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

Every sentence earns its place: purpose is front-loaded, the use-case analogy is one sentence, and the side-effect guarantee is a short closing statement. There is no filler or repetition.

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

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

Given the presence of an output schema, two well-described parameters, and a clear no-side-effects guarantee, the description fully equips an agent to select and invoke the tool correctly. It also explains the business motivation, which is not captured by the structured fields.

Complex tools with many parameters or behaviors need more documentation. 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 already provides complete descriptions for both parameters at 100% coverage, including where dpop_token comes from and the expected npub format. The tool description adds little parameter-level meaning beyond the word 'previously-cached,' so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Check whether a previously-cached dpop_token is still valid.' It also connects to the npub-proof flow and names the check_oauth_status analog, making it easy for an agent to distinguish this from the many other status and check 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?

It gives a clear use case: ask whether the next paid call will accept the dpop_token before burning credits on a guaranteed failure. It names check_oauth_status as the analog, though it does not explicitly say when not to use this tool or list alternatives.

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

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

No annotations are provided, so the description must 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that deletion is keyed on vaulted fields rather than template-declared fields, that it is idempotent with `removed: false` on already-absent fields, that it does not rewrite the vault in that case, that operator proof is required, and that deletion is as destructive as a write.

Agents need to know what a tool does to the 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 dense but every sentence earns its place: action, counterpoint, use case, idempotency, auth, and destructiveness. It front-loads the core behavior and then layers in selection guidance and caveats without repetition or filler.

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

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

For a destructive, auth-gated, idempotent mutation tool with no annotations, the description covers everything needed to call it correctly: what it deletes, how field keying works, when to use it, proof requirements, idempotent behavior, and destructive nature. The output schema can handle return-value details, so nothing critical 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?

Although schema coverage is 100%, the description adds meaningful context to both parameters. It clarifies that `field` may be templated or not and is matched against what is vaulted rather than the current template, and it explains what counts as a valid `dpop_token` proof (nsec-signed kind-27235 or cached dpop_token phrase), including that patron proofs fail.

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

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

The description opens with a specific verb and resource: 'Remove a single operator secret field' and immediately explains it deletes one key from the operator's encrypted credential blob without touching others. It explicitly contrasts itself with the sibling `forget_credentials` (whole-row wipe), so an agent can distinguish the tools without opening either schema.

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

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

The description gives concrete when-to-use guidance: retire a leftover after an SDK cutover, with named examples (Prefect key after Modal, `anthropic_api_key` orphan). It also states when it is not appropriate — patron proofs are rejected — and positions it as the field-level alternative to `forget_credentials`.

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

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

With no annotations, the description carries the behavioral burden. It discloses that proof of npub ownership is required, that this is a sensitive write to the credential vault, and that it is free. These are meaningful behavioral traits beyond the plain 'delete' semantics. It does not cover idempotency or behavior when the field is missing, but the provided context is strong.

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

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

The description is short, front-loaded with the primary action, and each sentence conveys information: targeted deletion, non-destructive scope, cost, and auth requirement. The first two sentences are mildly redundant ('Remove' and 'Deletes'), which prevents a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3-parameter tool with an output schema, the description covers the essential operational context: what is deleted, what is preserved, the proof requirement, the sensitive-write nature, and the cost. It does not explain when to prefer sibling credential tools, but the description is otherwise complete enough for safe invocation.

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

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

Schema description coverage is 100%, so the input schema fully documents each parameter. The description does not add parameter-level details beyond what the schema provides, which is acceptable under the baseline. It only loosely reinforces the 'field' parameter via 'one field.'

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

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

The description uses a specific verb and resource: 'Remove a single patron credential field' and 'Deletes one field from stored credentials.' It clearly distinguishes from sibling tools like taxsort_delete_operator_credential by specifying 'patron' and from update-style tools by specifying deletion.

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

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

The description implies when to use the tool: when deleting exactly one patron credential field while preserving others. It does not explicitly mention alternatives or when not to use it, such as using taxsort_forget_credentials for bulk removal or taxsort_update_patron_credential for edits. Usage context is present but left to inference.

Agents often have multiple tools that could apply. Explicit usage 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?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It clearly warns that deletion is destructive and that proof of npub ownership is always required. It could go further on irreversibility or side effects, but the destructive/auth context is significantly better than a bare 'delete' statement.

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

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

The description is compact and front-loaded with the primary action. Each sentence earns its place: the purpose, the npub selection rule, and the critical destructive-auth warning. No fluff or redundant schema repetition.

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

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

The description covers the essential destructive nature and authentication requirement, and an output schema exists so return-value documentation is not needed. However, the presence of sibling tools like taxsort_delete_operator_credential and taxsort_delete_patron_credential creates real ambiguity about which endpoint to call, and the description does not resolve 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 already has 100% coverage with detailed descriptions, so the baseline is 3. The description adds value by clarifying the operator-versus-patron meaning of the npub parameter and reinforcing the dpop_token proof requirement. This goes beyond simply restating the schema.

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

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

The description states a clear action ('Delete vaulted credentials') with a specific resource scope ('for a specific service and npub'). It is not a tautology and conveys the tool's core operation, but it does not distinguish it from closely named siblings like taxsort_delete_operator_credential and taxsort_delete_patron_credential.

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

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

The description provides useful context about when to pass an operator's npub versus a patron's npub and stresses that proof of ownership is required. However, it does not explain when this tool should be chosen over the similarly-purposed sibling delete/forget tools, leaving the selection decision somewhat ambiguous.

Agents often have multiple tools that could apply. Explicit usage 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 carries the full behavioral burden. It conveys the core non-mutating behavior (generating a proof from a stored notarization) and the semantic meaning of the proof, but it does not disclose failure modes, such as behavior for an unknown notarization_id or a patron not included in the snapshot, nor any authorization 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?

A single 19-word sentence with the verb and resource front-loaded. Every word carries meaning, and there is no filler, repetition, or boilerplate — an example of genuine economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 2-parameter tool with 100% schema coverage and an output schema present, the description is largely sufficient for correct invocation. The main gaps are unstated edge-case semantics and the absent usage relationship to the npub_proof siblings, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so the baseline of 3 applies; the schema already documents npub (Nostr public key, npub1... format) and notarization_id. The description adds only modest connective meaning by mapping 'patron's balance' to npub and the snapshot to notarization_id, with no additional parameter-level detail 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?

States a specific verb ('Generate') and a specific, technically precise resource ('Merkle inclusion proof' of a patron's balance in a 'Bitcoin-notarized snapshot'). The terminology distinguishes it from overlapping siblings such as taxsort_request_npub_proof and taxsort_receive_npub_proof, which suggest different stages of the proof lifecycle, and from taxsort_check_proof_status, which implies status checking rather than generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 given, and no alternative tools are named. The usage context is implied by the specific wording — call this when you need cryptographic proof of balance inclusion in a notarized snapshot — but an agent must infer exclusions and edge cases on its own.

Agents often have multiple tools that could apply. Explicit usage 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?

With no annotations, the description carries the full behavioral burden, and it is thorough: it discloses that values are never exposed, that older vaulted secrets yield null timestamps, that the field list is sensitive, and that the operation is free. This goes well beyond the schema in telling the agent what the call will and will not do.

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

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

The description is compact and well-structured: purpose comes first, followed by return details, caveats, use case, and prerequisites. Every sentence contributes useful information, with no redundant restatement of tool name or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 100% schema coverage, an output schema, and a read-only listing behavior, the description covers everything an agent needs to call this tool correctly: required proof, expected return fields, timestamp semantics, and sensitivity. Nothing critical 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 100%, so the baseline is 3. The description adds context around the tool's output and sensitivity rather than new parameter semantics; the npub and dpop_token fields are already fully documented in the input 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 opening line 'List stored patron credential field names (not values)' gives a specific verb, resource, and scope, and immediately distinguishes this from value-returning or credential-mutating siblings. The follow-up clarifies it returns names and timestamps, not secrets, making the tool's 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 states a clear intended use: 'use this to verify which fields are configured and how old each one is.' It also tells the agent not to expect values ('Values are never exposed') and notes that ownership proof is required. It does not explicitly name alternative tools for value retrieval, so it falls just short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the proof-of-ownership requirement, explains why credential presence is sensitive, states that the tool is free, and describes behavior across service types. It does not explicitly say the operation is read-only, but the verb 'Report' and the sensitivity framing strongly imply a non-mutating read.

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

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

The description is three short paragraphs, each with a distinct job: stating the purpose, describing service-type behavior, and explaining cost/auth rationale. Every sentence adds value and there is no filler or redundancy.

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

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

With an output schema present and only two parameters fully covered by the schema, the description supplies everything needed to invoke this tool correctly: behavior, authorization requirements, sensitivity rationale, cost, and service-type distinctions. Nothing critical is missing for an agent to select and use 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 100%, so the schema already documents both parameters and the baseline is 3. The description adds meaning beyond the schema by explaining why dpop_token is required ('Proof of npub ownership is required') and by connecting it to the sensitivity of credential presence, which helps an agent understand the parameter's purpose rather than just its 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?

The first sentence uses a specific verb ('Report') with a clear resource ('patron's credential readiness') and scope ('for this operator'). The rest of the description spells out exactly what is shown for set-once services versus dynamic/OAuth2 services, which clearly distinguishes it from sibling tools like get_operator_onboarding_status and get_patron_credential_fields.

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

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

The description provides clear context: use this tool to check whether patron secrets are configured for set-once services and to confirm no credentials are needed for dynamic services. It also states conditions such as proof of npub ownership and that the tool is free, but it does not explicitly name alternatives or state 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?

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 are provided, so the description carries the full burden of behavioral disclosure. 'List' implies a read operation, but the description does not state whether authentication is required, how records are ordered, what 'recent' means in time terms, or whether the records are scoped to the current user. For a tool with zero annotation coverage, this is a thin disclosure.

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

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

A single five-word sentence with zero wasted words, front-loaded with the verb and resource. It is concise, but borders on under-specification: the qualifier 'recent' is vague and the sentence misses the opportunity to note the status filter or ordering behavior that would help an 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?

The tool is simple, has an output schema (so return values need not be explained), and both parameters are well documented in the schema. However, with no annotations, the description leaves behavioral context (read-only safety, sorting, scope of 'recent') to inference, and it offers no orientation among the several notarization-related 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 100%, so the schema already documents both parameters: limit ('Maximum records to return (default 20)') and status ('Optional filter...'). The description adds no parameter-level information, which is acceptable given the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb ('List'), resource ('Bitcoin notarization records'), and scope ('recent'). It is clearly a read-oriented enumeration tool and the naming matches sibling conventions (list_*). However, it does not explicitly differentiate itself from closely related siblings like taxsort_get_notarization_proof or taxsort_notarize_ledger, though the list-vs-single distinction is reasonably inferable.

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

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

There is no guidance on when to use this tool versus alternatives. With siblings like taxsort_get_notarization_proof, taxsort_check_proof_status, and taxsort_notarize_ledger in the same domain, an agent gets no help choosing between listing records and fetching a specific proof. No exclusions or alternative conditions are mentioned.

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

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

With no annotations, 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.