This MCP server computes Canadian Adjusted Cost Base (ACB) and capital gains from trade history using CRA rules, returning structured JSON results.
Tools:
calculate_acb – Full ACB & capital gains calculation: current holdings (shares, total ACB, ACB per share), every disposition (proceeds, ACB, outlays, gain/loss), superficial-loss detection, per-tax-year summaries (net & taxable capital gains at 50% inclusion), and warnings.
acb_summary – Lightweight view of current holdings (shares, total ACB, ACB per share) — useful for tracking unrealized gains.
capital_gains_report – Schedule 3-style report for a specific tax year: each disposition's details plus totals (proceeds, ACB, net and taxable capital gain), with superficial losses already applied.
check_superficial_losses – Identifies losses caught by the CRA 30-day (61-day window) rule, reporting the denied/deferred amount and how it's added to the ACB of substitute shares.
Input: Transactions can be provided inline (JSON array) or via a CSV/JSON file path. Supported fields include date, action (buy/sell), security, shares, price, commission, currency, and fx_rate for CAD FX conversion.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@acb-tax-mcp What are my capital gains for 2024?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that computes Canadian adjusted cost base (ACB) and capital gains from your trade history: average-cost tracking, per-disposition gains, and superficial-loss detection, returned as structured JSON.
Ask your assistant "what are my capital gains for 2024?" or "did I trigger any superficial losses?" and it runs the CRA rules over your transactions instead of you wrestling a spreadsheet.
⚠️ This is a calculation aid, not tax advice. Verify every number before you file, and consult a professional for anything non-trivial. See Limitations.
Works with Claude Desktop, Claude Code, Cursor, or any MCP-compatible client.
Tool | What it does |
| Full calculation: current holdings (shares, total ACB, ACB per share), every disposition with proceeds/ACB/outlays/gain, per-year summaries, and warnings. |
| Just current holdings and their book cost (handy for unrealized gains against a market price). |
| A Schedule-3-style report for one tax year: each disposition plus totals, net capital gain, and taxable gain (50% inclusion). |
| One aggregated row per security in the exact Schedule 3 column shape: shares, gross proceeds, ACB, outlays (commissions), gain/loss after the superficial-loss rule, acquisition years, and totals -- the lines you actually transcribe when filing. |
| Flags losses caught by the 30-day rule, with the denied (deferred) amount per event. |
| Current holdings' ACB against market prices you supply: per-position and total unrealized gain in dollars and percent (foreign-quoted securities take a price + fx_rate pair). |
| Turns a raw broker activity export into clean transactions: maps common column aliases ("Trade Date", "Activity Type", "Quantity"...), keeps buy/sell rows (DRIP counts as a buy), cleans "$1,200"/"(9.95)" formats, and reports every skipped row with a reason. |
Implements the CRA average-cost method (all shares of a security pool into one ACB; gains are against the average, not FIFO) and the superficial-loss rule (loss denied and deferred into the ACB of substitute shares bought within 30 days before or after the sale). Commissions and per-trade CAD FX conversion are handled.
Related MCP server: ibkr-mcp
No install needed to try it: open the Glama server page and use Try in Browser to call the tools against a sandbox with a couple of sample transactions.
Requires Python 3.10+.
uv tool install acb-tax-mcp # or: pip install acb-tax-mcpRun from source without installing:
git clone https://github.com/haiiibin/acb-tax-mcp
cd acb-tax-mcp
uv run acb-tax-mcpIn claude_desktop_config.json:
{
"mcpServers": {
"acb-tax": {
"command": "acb-tax-mcp"
}
}
}claude mcp add acb-tax -- acb-tax-mcpGive the tools a list of transactions (or a path to a .csv / .json file).
Field | Required | Notes |
| yes |
|
| yes |
|
| yes | ticker / symbol (pooled by this key) |
| yes | positive number |
| yes | price per share, in the trade currency |
| no | trade commission (default 0) |
| no | e.g. |
| no | trade currency to CAD, e.g. |
| no | free text |
CSV uses the same column names as a header row. If your broker's export uses different headers ("Trade Date", "Activity Type", "Symbol", "Quantity"...), run it through normalize_broker_csv first.
Want something to try immediately? examples/sample_trades.csv is a ready-made broker-style export with aliased headers, $-formatted numbers, a DRIP row, a dividend row (skipped with a reason), a USD trade with FX, and a superficial-loss scenario. Ask your assistant to clean it with normalize_broker_csv and run calculate_acb on the result.
"Calculate the ACB and capital gains for the trades in ~/trades.csv."
"What's my capital-gains report for 2024?"
"Did any of these sales trigger a superficial loss?"
"What's my current book cost for XEQT?"
"Here's my RBC activity export -- clean it up and compute my ACB."
"XEQT is at $35.20 and VTI at $305.40 USD (1.37 CAD): what are my unrealized gains?"
// calculate_acb with:
// buy 100 XYZ @ $10, buy 100 XYZ @ $20, sell 100 XYZ @ $25
{
"holdings": [
{ "security": "XYZ", "shares": 100.0, "total_acb": 1500.0, "acb_per_share": 15.0 }
],
"dispositions": [
{ "date": "2024-03-01", "security": "XYZ", "shares_sold": 100.0,
"proceeds": 2500.0, "acb": 1500.0, "capital_gain": 1000.0,
"is_superficial_loss": false }
],
"summary": {
"by_tax_year": [
{ "tax_year": 2024, "net_capital_gain": 1000.0, "taxable_capital_gain": 500.0 }
],
"inclusion_rate": 0.5
}
}Buy 100 @ $10, sell 100 @ $8 (a $200 loss), then rebuy 100 @ $8 nine days later:
{ "gain_before_superficial": -200.0, "superficial_loss_denied": 200.0,
"capital_gain": 0.0, "is_superficial_loss": true }The $200 loss is denied and added to the ACB of the repurchased shares (new ACB per share becomes $10), so it is recovered on a future sale.
Read these before relying on the output.
Average-cost, per identical property. Feed all trades of the same security across your accounts together, since the CRA rule pools identical property at the taxpayer level. The tool pools by the security key you provide.
Superficial losses use the standard least-of-three test with a single forward pass. Deeply chained or overlapping superficial losses can need case-by-case professional judgment.
Not yet handled: return of capital, reinvested/notional distributions (ETF phantom distributions), stock splits, options, and other corporate actions. These affect ACB and are on the roadmap.
FX must be supplied per transaction (use the transaction-date rate). The tool does not fetch exchange rates.
Registered accounts (TFSA/RRSP) do not have capital gains; this tool is for non-registered (taxable) accounts.
Not tax advice.
uv venv
uv pip install -e ".[dev]"
uv run pytestMIT. See LICENSE.
Show current holdings: shares, total ACB and ACB per share for each security.
A lighter view than calculate_acb when you only want the current book cost of what is still held (for example to compute an unrealized gain against a market price). Accepts inline 'transactions' or a 'csv_path'. Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains input formats (transactions or csv_path) and output (holdings, shares, ACB). However, it does not disclose what happens with empty inputs, error behavior, or the exact output structure beyond general fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with two paragraphs: first states purpose, second gives parameter details. It is informative without being verbose. Minor improvement could be front-loading the comparison earlier, but overall concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers inputs thoroughly and explains what the output shows (holdings, shares, ACB). It lacks mention of error handling or edge cases, but is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (parameters anyOf without description), but the description fully details both parameters: 'transactions' as an array of objects with required and optional fields (date, action, security, shares, price, etc.) and 'csv_path' as a path. This adds essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows current holdings (shares, total ACB, ACB per share) and distinguishes itself from the sibling tool 'calculate_acb' by noting it's a lighter view for current book cost. Purpose is specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'when you only want the current book cost of what is still held' and contrasts it with 'calculate_acb'. It does not exclude other siblings but provides a clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute adjusted cost base and capital gains for a set of trades (Canadian rules).
Runs the full calculation and returns: current holdings (shares, total ACB, ACB per share) per security; every disposition with proceeds, ACB, outlays, the gain before and after the superficial-loss rule, and whether it was a superficial loss; per-tax-year summaries with net and taxable capital gain; and any warnings.
Uses the CRA average-cost method (all shares of a security pool into one ACB; gains are computed against the average, not FIFO). Pass trades either inline as 'transactions' or as a file path in 'csv_path' (CSV or JSON). Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
This is a calculation aid, not tax advice; verify results before filing.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the calculation method (average-cost, not FIFO), the types of outputs, and that it is a tax aid requiring verification. It does not mention potential limitations (e.g., number of trades) or errors, but the disclosed behaviors are clear and sufficient for basic usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured in three paragraphs: purpose, outputs, and input format. It is concise with no fluff, but it could be slightly shortened by combining sentences. The key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a tax calculation tool with 2 parameters and no output schema, the description provides detailed output types, input formats, and a warning. It covers the major aspects, though it lacks details on error handling, maximum trade counts, or currency handling. Overall, it is sufficiently complete for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so extensively: it defines 'csv_path' as a file path for CSV/JSON, and 'transactions' as an array of objects with detailed structure (date, action, security, shares, price, etc.), adding critical meaning beyond the schema's minimal typing.
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 computes adjusted cost base and capital gains for trades under Canadian rules, using the CRA average-cost method. It specifies the outputs (holdings, gains, summaries, warnings). However, it does not explicitly differentiate itself from sibling tools like 'acb_summary' or 'capital_gains_report', leaving some ambiguity about when to use this tool over alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to pass trades (inline or file path) and provides transaction structure. It includes a disclaimer about being a calculation aid. However, it does not give explicit guidance on when to use this tool vs. siblings, such as whether to use this for full calculations or 'acb_summary' for summaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Produce a capital-gains report for a single tax year (Schedule 3 style).
Returns every disposition dated in 'tax_year' with proceeds, ACB, outlays and the allowable capital gain/loss, plus totals: total proceeds, total ACB, net capital gain, and the taxable capital gain (net gain times the 50% inclusion rate). Superficial losses are already applied. Accepts inline 'transactions' or a 'csv_path'. Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
This is a calculation aid, not tax advice; verify results before filing.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| tax_year | Yes | ||
| transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently explains the tool accepts inline transactions or a CSV path, applies superficial losses, and produces a detailed report. It also includes a disclaimer that it is not tax advice. However, it does not mention error handling, rate limits, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the primary purpose. Each sentence adds value, covering what the tool does, input options, output details, and a cautionary note, without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output (dispositions with proceeds, ACB, etc., plus totals) despite no output schema. It covers the key input parameters and limitations. However, it lacks discussion of error scenarios or edge cases, which would enhance completeness for a tool with no external 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?
With 0% schema description coverage, the description compensates well. It explains the tax_year parameter, the choice between csv_path and transactions, and provides a detailed breakdown of the transaction object format (date, action, security, shares, price, optional fields). This adds meaning beyond the schema's basic type definitions.
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 produces a capital-gains report for a single tax year (Schedule 3 style), listing dispositions with proceeds, ACB, outlays, and totals. It distinguishes from sibling tools (acb_summary, calculate_acb, check_superficial_losses) by focusing on a comprehensive report rather than just ACB or loss calculations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool over siblings or alternatives. It only mentions it is a calculation aid and advises verifying results, but lacks context for selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag superficial losses under the CRA 30-day (61-day window) rule.
Scans dispositions for losses where the same security was bought within 30 days before or after the sale and still held at the end of that window. For each, reports the security, date, the denied (deferred) loss amount and the allowable portion. The denied amount is added to the ACB of the substitute shares. Accepts inline 'transactions' or a 'csv_path'. Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses the tool's behavior: scans dispositions, identifies losses under the 30-day rule, and reports security, date, denied amount, and allowable portion. Also explains that denied amount is added to ACB of substitute shares. No annotations provided, so the description carries the full burden and does so excellently.
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?
Front-loaded with purpose in the first sentence. Structured logically: rule explanation, output description, then input format. Every sentence adds value; no redundancy. Efficient and clear.
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 no output schema and no annotations, the description provides everything needed: input format, behavior logic, and output fields. The complexity of the CRA superficial loss rule is well-explained, making the tool fully understandable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully compensates by explaining both parameters: csv_path for file input and transactions for inline data. It also defines the transaction object structure in detail (date, action, security, shares, price, optional fields), adding significant meaning beyond parameter names.
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 flags superficial losses under the CRA 30-day rule. Uses specific verb 'Flag' and resource 'superficial losses'. Distinguishes from sibling tools like acb_summary and calculate_acb, which handle general ACB or capital gains, not superficial loss detection.
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?
Describes what the tool does in detail, including the rule it applies and the input formats. Provides clear context but does not explicitly state when to use versus alternatives or when not to use. However, the purpose is distinct from siblings, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a raw broker activity export into transactions the other tools accept.
Broker exports rarely match the documented headers. This tool maps common column aliases ("Trade Date", "Activity Type", "Symbol", "Quantity", ...), keeps only buy/sell rows (reinvestment/DRIP rows count as buys, since they add to ACB), cleans number formats ("1,200", "$9.99", parenthesized negatives, signed quantities), and returns ready-to-use 'transactions' plus a per-row 'skipped' list (dividends, deposits, transfers, unparseable rows) with reasons, so nothing is dropped silently. Pass the export as 'csv_path' (CSV/TSV/JSON) or inline as 'rows'. Feed the returned transactions straight into calculate_acb, capital_gains_report or unrealized_gains.
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | ||
| csv_path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: maps common column aliases, keeps only buy/sell rows (including DRIP as buys), cleans number formats, and returns both 'transactions' and 'skipped' lists with reasons. No annotations, so description bears full burden; adequately 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?
Well-structured with front-loaded purpose followed by details. Each sentence adds value, though slightly verbose. Could be trimmed without losing meaning.
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, no output schema, and sibling tools that are downstream, the description fully explains the output format (transactions, skipped list) and integration flow. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must add value. It explains that 'csv_path' accepts CSV/TSV/JSON file paths and 'rows' can be inline array, and mentions common column aliases. However, it does not detail the exact structure required for each row object, leaving some ambiguity.
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 specifies verb 'normalize' and resource 'broker CSV', explaining it converts raw exports into transactions for other tools. Distinguishes from siblings by describing its role as a preprocessing step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (raw broker CSV with mismatched headers) and directs output to downstream tools (calculate_acb, capital_gains_report, unrealized_gains). Lacks explicit when-not-to-use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One row per security in the shape of Schedule 3's publicly traded shares section.
Aggregates dispositions (optionally limited to 'tax_year') into one line per security with the columns transcribed onto Schedule 3: number of shares, proceeds of disposition (gross, before commissions), adjusted cost base, outlays and expenses (sale commissions), and gain or loss with the superficial-loss rule already applied, plus acquisition years, per-column totals, and the list of years that have dispositions. capital_gains_report lists every individual disposition; use this tool when the user wants the aggregated filing lines instead. Accepts inline 'transactions' or a 'csv_path'. Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
This is a calculation aid, not tax advice; verify results before filing.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| tax_year | No | ||
| transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: applies the superficial-loss rule, provides per-column totals, and includes a caution that it's a calculation aid. However, it does not explicitly state whether the tool is read-only or describe error handling, but the specifics given 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?
The description is well-structured and information-dense without fluff. Each sentence adds value: output shape, aggregation details, sibling distinction, input options, transaction schema, and a disclaimer. It is front-loaded with the core purpose and then elaborates.
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, the description is complete. It covers what the tool does, how it behaves (superficial-loss rule), what inputs are accepted, what outputs look like (columns and totals), and includes a necessary legal caution. No critical aspect 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?
The schema provides no parameter descriptions, but the description compensates fully. It explains tax_year as an optional filter, csv_path versus transactions as alternative inputs, and details the transaction object structure with all fields and examples (e.g., fx_rate 1.35 for USD).
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: it aggregates dispositions into one line per security for Schedule 3. It uses a specific verb ('aggregates') and identifies the resource ('dispositions'), and distinguishes itself from the sibling capital_gains_report.
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 explicitly says when to use this tool versus the alternative: 'capital_gains_report lists every individual disposition; use this tool when the user wants the aggregated filing lines instead.' It also explains that it accepts inline transactions or a csv_path, giving clear input options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute unrealized gains: current holdings' book cost (ACB) against market prices.
For each security still held, returns shares, total ACB, current market value and the unrealized gain in dollars and percent, plus portfolio totals. 'market_prices' maps each security to its current price: either a number already in CAD (e.g. {"XEQT": 35.20}) or, for foreign-quoted securities, an object with the trade-currency price and the CAD exchange rate (e.g. {"VTI": {"price": 305.40, "fx_rate": 1.37}}). Held securities without a price are listed in 'missing_prices' and excluded from totals. Accepts inline 'transactions' or a 'csv_path'. Each transaction is an object: date (YYYY-MM-DD), action ('buy' or 'sell'), security (ticker/symbol), shares, price (per share), and optionally commission, currency, fx_rate (trade-currency to CAD, e.g. 1.35 for USD), and note.
| Name | Required | Description | Default |
|---|---|---|---|
| csv_path | No | ||
| transactions | No | ||
| market_prices | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It thoroughly explains input formats, handling of missing prices (listed in missing_prices and excluded), and output structure. It does not mention side effects, but for a compute-only tool, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 150 words, well-organized into purpose/output in first paragraph and parameter details in second. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, nested objects, and no output schema, the description explains inputs and outputs sufficiently, including special cases like missing prices. It mentions the output structure clearly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully details all parameters: csv_path (optional path), transactions (array of objects with all fields), and market_prices (required object with number or {price, fx_rate} per security). This compensates completely.
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 computes unrealized gains using ACB against market prices, listing outputs per security and totals. It implicitly distinguishes from siblings like calculate_acb (which computes ACB without market prices) and capital_gains_report (realized gains).
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 what the tool does and how to format inputs, but does not explicitly state when to use it versus alternatives like capital_gains_report for realized gains. It provides clear context but no exclusions.
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.
v0.4.0schedule3_summaryv0.2.2normalize_broker_csvunrealized_gainsv0.1.0acb_summarycalculate_acbcapital_gains_reportcheck_superficial_lossesScored across 7 tools
Each tool has a clear purpose: calculate_acb runs the full computation, acb_summary gives a lighter holdings view, capital_gains_report lists dispositions per year, schedule3_summary provides aggregated filing lines, check_superficial_losses handles a specific rule, unrealized_gains handles market comparison, and normalize_broker_csv handles data ingestion. There is some overlap between acb_summary and calculate_acb, and between capital_gains_report and schedule3_summary, but each serves a distinct user need.
The naming mixes verb_noun patterns (calculate_acb, check_superficial_losses, normalize_broker_csv) with noun phrases (acb_summary, capital_gains_report, schedule3_summary, unrealized_gains). This is inconsistent but still readable and mostly clear.
7 tools is within the typical range. Each tool has a distinct purpose and covers the domain of ACB/tax calculations well. Not too many, not too few.
The toolset covers input normalization, full ACB calculation, summaries, per-year reports, Schedule 3 aggregation, superficial loss checking, and unrealized gains. Gaps might include things like ACB adjustment events (e.g., return of capital) or tax-loss harvesting suggestions, but for the stated purpose of ACB/tax calculations, it's fairly complete.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
MCP server for stocksense-ai documentation, generated by doc2mcp.
Multi-tenant FastMCP server for Charles Schwab brokerage data, monetized via DPYC Tollbooth
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
