Crypto cost-basis lots (FIFO/LIFO/HIFO/specific-ID), Form 8949 rows, 1099-DA diff. 5 of 8 free.
Build the lot inventory per account and every disposal with basis, gain and holding period. PREMIUM (license).
Methods: fifo (the default rule when no specific identification is made, Treas. Reg. 1.1012-1(j)), lifo, hifo, or specific_id via a row's specific_lots {lot_id: qty}. Typical input {"ledger": , "method": "hifo", "transfers": } returns {"disposals": [{"row": "cb9", "asset": "BTC", "qty": "0.5", "proceeds": "31000.00", "basis": "20000.00", "gain": "11000.00", "term": "long", ...}], "open_lots": [...], "summary": {"short_term": {...}, "long_term": {...}}}. Fees: a cash purchase's fee joins basis; a sale's or exchange's fee reduces the amount realized (1.1001-7); a network fee paid in the transferred asset is a disposal of those units (transfer_fee_policy dispose) unless you choose ignore. Transfers between your own accounts move lots with their basis and acquisition date. Use once ledger_lint reports no errors. Not tax advice: it applies the stated rules to your rows and shows its work. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "method must be fifo, lifo, hifo or specific_id"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| ledger | Yes | canonical rows. | |
| method | No | fifo, lifo, hifo or specific_id (rows without specific_lots fall back to fifo). | fifo |
| tax_year | No | when set, only disposals in that calendar year are returned (the inventory still runs from the start). | |
| transfers | No | pairs from match_transfers ({"out": id, "in": id, ...}); empty to auto-match with the defaults. | |
| on_missing_lots | No | error (default), or zero_basis for lenient mode - disposals beyond the lots held get zero basis and unmatched transfer_out rows simply leave the inventory, each flagged. | error |
| transfer_fee_policy | No | dispose (default) or ignore for network fees paid in the transferred asset. | dispose |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing exact error behavior ('never raises a protocol error — it returns {"error": ...}'), detailed fee handling rules, transfer treatment, and the read-only/idempotent retry guarantee. These behavioral details add substantial operational context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and organized into clear sections for methods, fees, transfers, usage timing, and errors. It is long, with an extended example and legal disclaimers, but each section contributes meaningful information, so it remains purposeful rather than bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tax-calculation complexity, the description covers everything needed: preconditions, all method options, fee policies, transfer behavior, error semantics, and output structure. An output schema exists, so the example return shape is a bonus rather than a requirement, making the definition 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?
Although schema coverage is 100%, the description adds rich meaning: tax regulation citations for fifo, the specific_id fallback rule, fee basis treatment, transfer_fee_policy semantics, and a concrete input/output example. This is far beyond what the schema properties describe.
Input schemas describe structure but not intent. Descriptions should explain 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: 'Build the lot inventory per account and every disposal with basis, gain and holding period.' This clearly states the tool's unique role among siblings and distinguishes it from validation (ledger_lint), transfer matching (match_transfers), and reporting (form_8949_rows).
Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit precondition: 'Use once ledger_lint reports no errors,' and references match_transfers output as input, clarifying sequencing and data flow. However, it does not explicitly list when not to use this tool or name alternatives for the same task, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lay the disposals out as Form 8949 rows with box categories and totals. PREMIUM (license).
Typical input {"disposals": , "tax_year": 2026, "default_reporting": "proceeds_only"} returns {"part_i": {"B": [rows]}, "part_ii": {"E": [rows]}, "totals": {...}}. Columns follow the form: description (a), date acquired (b), date sold (c), proceeds (d), cost or other basis (e), code (f), adjustment (g), gain or loss (h). Box: A/D when the broker reported proceeds and basis, B/E when proceeds only, C/F when no broker form - set per row in reporting {row_id: value} or for all rows with default_reporting. Use to draft the schedule from computed disposals. Not a filing: check the current form instructions. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "disposals must be a non-empty list from build_lots"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_year | Yes | the calendar year of the disposals to include. | |
| disposals | Yes | rows from build_lots. | |
| reporting | No | per-row override: proceeds_and_basis, proceeds_only or none. | |
| whole_dollars | No | round each row to whole dollars as the form permits. | |
| default_reporting | No | proceeds_and_basis, proceeds_only or none (default). | none |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses important behavior: it never raises a protocol error and returns a structured error object with remediation guidance, it is safe to retry after correction, and it produces category-specific output (part_i/part_ii and box groupings). It also clarifies that it is not a filing action, adding meaningful context beyond the 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 longer than average but each major block earns its place: purpose, example, column mapping, box logic, usage note, error behavior, and retry safety. It is front-loaded with the core purpose. Minor redundancy exists—read-only and idempotent are already in annotations—and the 'PREMIUM (license)' note is irrelevant noise, but overall it is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five parameters, nested objects, an output schema, and meaningful sibling relationships, the description is remarkably complete. It covers the required input source, the output shape, box category logic, parameter overrides, error behavior, and the non-filing caveat. An agent has enough context to select and invoke the tool correctly without inspecting other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter. The description adds valuable meaning by showing a typical input shape, explaining that disposals must come from build_lots, clarifying the reporting/default_reporting values and box mappings, and illustrating the output structure. This exceeds the baseline but does not exhaustively expand on every 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 opens with a specific verb and resource: 'Lay the disposals out as Form 8949 rows with box categories and totals' and later says 'Use to draft the schedule from computed disposals.' It clearly differentiates from siblings by tying the input to build_lots and positioning the tool as form drafting rather than lot building, transfer matching, or reconciliation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('Use to draft the schedule from computed disposals') and gives a strong usage precondition ('disposals from build_lots'). It also warns 'Not a filing: check the current form instructions,' which helps set expectations. It does not name alternative tools or explicitly state when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the problems that break a lot build: missing values, duplicates, negative balances. FREE.
Typical input {"ledger": } returns {"issues": [{"severity": "error", "row": "cb12", "issue": "sell of 0.5 BTC exceeds balance 0.2 in account coinbase"}], "balances": {"coinbase": {"BTC": "0.2"}}, "counts": {...}}. Balances are running quantities per account and asset in time order, ignoring transfers' fiat values. Use after parse_transactions and before build_lots. Not a tax check: it checks the ledger's arithmetic consistency only. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""}. Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| ledger | Yes | canonical rows (ts, type, asset, qty, fiat_value, fees, account...). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and idempotent annotations, the description reveals important behavior: it never raises a protocol error, returns an error object with remediation guidance, computes running balances in time order ignoring fiat values, and returns issues, balances, and counts. This is substantial context an agent needs to interpret results safely.
Agents need to know what a tool does to the 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 and front-loaded, with the core purpose stated first, followed by examples and edge-case behavior. The 'FREE.' fragment adds little and the read-only/idempotent sentence repeats annotations, but the overall structure is efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 single-parameter tool with an output schema and safety annotations, the description covers the input source, pipeline position, semantics, expected output, error contract, and exclusion of tax-checking. Nothing needed for correct invocation and interpretation 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the ledger param should contain rows from parse_transactions, lists the canonical fields, and clarifies how balances are computed. This exceeds schema-only documentation without fully expanding every row 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 names a specific action ('Find the problems that break a lot build') and resource (ledger), and enumerates concrete problem types: missing values, duplicates, negative balances. It also distinguishes its role in the pipeline from siblings by placing it between parse_transactions and build_lots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clearly states when to use the tool: after parse_transactions and before build_lots, and gives the expected input shape. It also states a when-not: 'Not a tax check.' It does not explicitly name alternative tools for other scenarios, but the pipeline positioning is strong enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Impermanent loss, hold-vs-pool value and basis split for a two-asset constant-product pool. FREE.
Typical input {"deposit": {"asset_a": "ETH", "qty_a": "1", "price_a": "2000", "asset_b": "USDC", "qty_b": "2000", "price_b": "1"}, "current_prices": {"ETH": "3000", "USDC": "1"}} returns {"il_pct": "-2.02", "hold_value": "5000.00", "pool_value": "4898.98", "deposit_value": "4000.00", "basis_split": {...}}. The pool value assumes x*y=k with no fees; add fees_earned_fiat to see the net. The basis split is the deposit's fiat value at deposit, allocated by each side's share, which is the arithmetic a lot engine needs if the LP position is treated as one asset. Use for DeFi position reviews. Not a determination of whether the deposit is a taxable exchange. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "deposit and current_prices must be objects"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| deposit | Yes | asset_a, qty_a, price_a, asset_b, qty_b, price_b at the time of deposit. | |
| current_prices | Yes | {asset: price} for both assets now. | |
| fees_earned_fiat | No | fees accrued to the position, in fiat. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral details beyond those: it never raises protocol errors and instead returns an error object with a fix, and retrying after correcting input is always safe. This is exactly the kind of runtime behavior an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then gives a compact example and error behavior. It is longer than average, but most sentences earn their place. The standalone 'FREE.' is minor noise, so it does not merit a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a rich input schema, full schema coverage, annotations, a nested-object example, output example, and explicit error-behavior guidance, the description is complete for an agent to select and invoke the tool correctly. The presence of an output schema also means the description need not enumerate return 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?
Schema coverage is 100%, so the schema already documents deposit, current_prices, and fees_earned_fiat. The description adds value by explaining that fees_earned_fiat adjusts the pool value to a net figure, and by providing a concrete typical input/output example that clarifies how the nested deposit object maps to values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it computes impermanent loss, hold-vs-pool value, and basis split for a two-asset constant-product pool. It also distinguishes this from tax-determination work by saying 'Not a determination of whether the deposit is a taxable exchange', which differentiates it from the sibling lot/tax 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 a clear when-to-use signal: 'Use for DeFi position reviews.' It also gives a when-not-to-use signal by clarifying it is not a taxable-exchange determination. However, it does not name or route to a specific alternative sibling tool, so it stops short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pair withdrawals with the deposits that received them between your own accounts. FREE.
Typical input {"ledger": , "window_minutes": 1440} returns {"pairs": [{"out": "kr91", "in": "cb14", "asset": "BTC", "from": "kraken", "to": "coinbase", "network_fee": "0.0001", "minutes": 42.0}], "unmatched": {"transfer_out": [...], "transfer_in": [...]}}. A pair needs the same asset, a different account, the deposit inside the window after the withdrawal, and a quantity within tolerance_pct of the amount sent net of the fee. Use before build_lots so basis and holding period move with the coins instead of being treated as a sale. Not for transfers to third parties: those stay unmatched and should be typed gift_out or sell. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""}. Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| ledger | Yes | canonical rows. | |
| tolerance_pct | No | allowed quantity difference in percent after the fee (default 1). | |
| window_minutes | No | how long after the withdrawal the deposit may land (default one day). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing error behavior ('never raises a protocol error — it returns {"error": ...}'), the matching criteria in detail, and the read-only/idempotent nature. It also explains the tax implication ('so basis and holding period move with the coins instead of being treated as a sale'), giving the agent important 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?
Despite being long, every sentence earns its place: purpose, example, matching criteria, usage timing, exclusions, error behavior, and idempotency. The information is dense but logically ordered and front-loaded with the core purpose, making it easy for an agent to extract the key facts quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an agent to call this tool correctly: it explains the input shape, output shape, matching rules, error handling, usage order relative to siblings, and what scenarios are out of scope. Combined with the rich input schema and annotations, 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 coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining tolerance_pct in context ('quantity within tolerance_pct of the amount sent net of the fee') and providing a typical input example with window_minutes. Ledger remains described only as 'canonical rows' in the schema, but the example and matching logic give enough practical context.
Input schemas describe structure but not intent. Descriptions should explain 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: 'Pair withdrawals with the deposits that received them between your own accounts.' This clearly distinguishes match_transfers from sibling tools like build_lots and parse_transactions by stating exactly what operation it performs and on what 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 explicitly states when to use the tool ('Use before build_lots'), what it is not for ('Not for transfers to third parties'), and what to do instead ('those stay unmatched and should be typed gift_out or sell'). This provides clear routing guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Normalise an exchange CSV export into the canonical ledger rows. FREE.
Supports the Coinbase transaction-history export (Transaction Type / Asset / Quantity Transacted columns), the Kraken ledgers export (txid / refid / type / asset / amount / fee) and a generic CSV with the canonical columns ts, type, asset, qty, fiat_value, fee_qty, fee_asset, fee_fiat, counter_asset, counter_qty, account, id. Typical input {"csv_text": "...", "source_hint": "coinbase"} returns {"rows": [...], "detected": "coinbase", "unrecognised": [...], "warnings": [...]}. Rows it cannot read are returned under unrecognised with the reason, never dropped silently. In every row qty is the whole amount that entered or left the account; when a fee was paid in the same asset, fee_qty is the part of qty that was the fee. Use before ledger_lint and build_lots. Not for other exchanges: convert those to the generic columns first. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "csv_text must be the CSV file contents"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | account label to stamp on every row (defaults to the source name). | |
| csv_text | Yes | the CSV file contents (up to 2 MB). | |
| source_hint | No | coinbase, kraken or generic; empty to detect from the header. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare read-only and idempotent behavior, the description adds substantial behavioral detail: unrecognized rows are never silently dropped, invalid input returns an error object rather than a protocol error, and the meaning of qty versus fee_qty is explained. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured and front-loaded with the core purpose. It is longer than average but nearly every sentence adds operational value. Minor redundancy like 'FREE' and restating idempotence costs it 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 parsing tool with this complexity, the description is complete: it covers supported formats, canonical columns, output shape, error behavior, unrecognized row handling, fee semantics, and recommended ordering relative to sibling tools. The agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining what the source_hint values imply (Coinbase and Kraken column layouts) and showing a typical input/output shape. This goes beyond the schema without being strictly necessary.
Input schemas describe structure but not intent. Descriptions should explain 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: 'Normalise an exchange CSV export into the canonical ledger rows.' It clearly defines what the tool does, names the supported export formats, and distinguishes its scope from other exchanges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use before ledger_lint and build_lots' and 'Not for other exchanges: convert those to the generic columns first.' This tells the agent when to use the tool and when not to, which is exactly what this dimension requires.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff the broker's 1099-DA lines against the computed disposals. PREMIUM (license).
Typical input {"disposals": , "form_rows": [{"asset": "BTC", "date_sold": "2026-03-04", "qty": "0.5", "proceeds": "31000", "basis": "", "account": "coinbase"}]} returns {"matched": [...], "broker_missing_basis": [...], "basis_mismatch": [...], "proceeds_mismatch": [...], "unmatched_form_rows": [...], "unmatched_disposals": [...]}. A line matches a disposal on the same account (when given), asset and sale date with quantity and proceeds inside the tolerances; several lots sold in one order are summed first. Use when the form arrives and the basis column is blank for coins that came from your own wallet. Not a substitute for the broker's statement. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "disposals must be a non-empty list from build_lots"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| disposals | Yes | rows from build_lots. | |
| form_rows | Yes | 1099-DA lines: asset, date_sold, qty, proceeds, basis (may be blank), account (optional), id (optional). | |
| money_tolerance | No | allowed proceeds/basis difference in fiat units (default 1.00). | |
| qty_tolerance_pct | No | allowed quantity difference in percent (default 0.5). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses meaningful behavioral details: it never raises a protocol error but returns a structured error object, it is read-only and idempotent, and it explains the matching algorithm with tolerances and lot summation. These details give an agent accurate expectations for execution and retry.
Agents need to know what a tool does to the 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 section earns its place: purpose, example input/output, matching rules, usage trigger, error behavior, and safety guarantee. It is front-loaded with the core purpose and organized so an agent can quickly extract the key 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 reconciliation tool with matching logic, tolerance parameters, and error handling, the description covers all critical aspects: input source, return categories, matching criteria, error format, retry safety, and a non-substitute caveat. An agent has enough context to invoke the tool correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes each parameter. The description adds value with a realistic input example, clarifies that basis may be blank, explains that tolerances govern matches, and notes that disposals come from build_lots. This goes beyond a baseline but does not need to fully compensate since the schema is strong.
Input schemas describe structure but not intent. Descriptions should explain 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 sentence 'Diff the broker's 1099-DA lines against the computed disposals' names a specific verb, resource, and operation. The tool is clearly distinguished from siblings like build_lots and form_8949_rows by its reconciliation role and the explicit 'Use when the form arrives...' trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case: 'Use when the form arrives and the basis column is blank for coins that came from your own wallet.' It also warns 'Not a substitute for the broker's statement.' However, it does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag loss disposals with a repurchase of the same asset inside the window. FREE.
Typical input {"disposals": , "acquisitions": [{"asset": "ETH", "ts": "2026-02-10T10:00:00Z", "qty": "2"}]} returns {"flags": [{"row": "cb7", "asset": "ETH", "loss": "-410.00", "repurchases": [...]}], "rule_status": "..."}. The 30-day window before and after the sale is the one IRC 1091 uses for stock or securities; as checked on the verification date that statute had not been extended to digital assets that are not securities, so the output is a heads-up for planning, not an adjustment. Use when reviewing loss harvesting. Not a determination that any rule applies. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ""} (for example {"error": "disposals and acquisitions must be lists"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| disposals | Yes | rows from build_lots (uses asset, disposed_at, gain, row). | |
| window_days | No | days before and after the loss disposal to scan (default 30). | |
| acquisitions | Yes | purchases/income rows with asset, ts, qty (ledger rows work as-is). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds non-obvious behavior: it never raises a protocol error and instead returns an error object with remediation guidance. It also discloses the legal significance of the output (heads-up, not an adjustment) and explicitly states retrying is safe after correcting input.
Agents need to know what a tool does to the 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 front-loaded with the purpose, followed by a compact example, legal context, usage guidance, and error behavior. Every sentence contributes something necessary; the example JSON and error format earn their place, and the length is justified by the nuance of the feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, input expectations, output shape, error semantics, legal caveats, and safety of retry. Since an output schema exists, the return format is already structured, and the description fills the contextual gaps around when and why to use the tool, making it fully complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds value beyond the schema by providing typical input and output examples, clarifying that disposals come from build_lots, and explaining the 30-day default via the IRC 1091 context. This exceeds the baseline for high 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 opening sentence uses a specific verb and resource: 'Flag loss disposals with a repurchase of the same asset inside the window.' This cleanly distinguishes it from sibling tools such as build_lots or form_8949_rows, and the example reinforces what the tool computes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states 'Use when reviewing loss harvesting' and warns 'Not a determination that any rule applies.' It provides clear context for when the tool is appropriate, though it does not name specific alternatives or exclusions, so it falls 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
build_lotsform_8949_rowsledger_lintlp_position_mathmatch_transfersparse_transactionsreconcile_1099dawash_window_checkClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Equity comp tax/trade optimizer: ISO/AMT exercise, NSO, RSU, QSBS, concentration, hedging. 50-state.
Deterministic MLP tax engine with IRS citations. 6 tools: basis, §751, estate, projections.
Document a §1001 sale of dead startup stock, SAFEs, notes, or LLC interests — capital loss records
US tax classification for on-chain transactions: category, treatment, confidence, review flags.
Add one secure layer between your agents and this server.
Each of the eight tools targets a distinct stage or analysis: import normalization, ledger validation, transfer pairing, lot building, Form 8949 formatting, broker-form reconciliation, wash-sale checking, and LP math. No two tools could be reasonably confused for one another.
Names are all lowercase snake_case and readable, but they mix verb_object forms like parse_transactions, match_transfers, and build_lots with noun-first compound forms like ledger_lint, lp_position_math, and wash_window_check. The convention is not uniform enough to be 'mostly consistent,' though it is still predictable from the domain.
Eight tools is a well-scoped size for a crypto tax-lot workflow; each tool covers a necessary step without redundant helpers. The count feels neither thin nor bloated.
The toolset covers the full pipeline from transaction import through linting, transfer matching, lot building, tax form row generation, 1099-DA reconciliation, and wash-sale review. The standalone LP math tool addresses a relevant adjacent need, and there are no obvious dead ends.
