OpenInvest

record_fee

Destructive

Records a paid fee or tax by debiting ledger cash and leaving positions unchanged, so it is booked as an account cost, not a withdrawal; fails if cash is insufficient.

Instructions

Record a fee or a tax the user already paid: debits ledger cash, positions unchanged. It is an account cost (inside NAV), not a withdrawal. Trade commissions need no separate entry — buy / sell already book the trade. Fails if the currency's cash balance is lower than the amount.

Confirm the amount and date with the user before calling; this moves ledger cash.

Args: amount: Amount paid; must be > 0. currency: Currency of the cash debited. kind: "fee" (default) or "tax". symbol: Related ticker (optional). trade_date: YYYY-MM-DD it was charged (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Cash debited and new balance, or {"status": "error", "error": ...}.

Input Schema

Name	Required	Description	Default
`kind`	No	'fee' (default: account / remittance / standalone commission) or 'tax' (e.g. dividend tax settled afterwards).	fee
`note`	No	Free-text note stored with the ledger row.
`amount`	Yes	Amount paid (positive number); must be > 0.
`symbol`	No	Ticker the fee/tax relates to (optional; omit for account-level).
`currency`	Yes	Currency the cash left in, e.g. 'CNY', 'USD', 'AUD'.
`trade_date`	No	Date the event happened, YYYY-MM-DD (default: today). Account performance books it on this date, so pass the real date when back-filling history.
`idempotency_key`	No	Optional client-generated key (e.g. a UUID4). When retrying this SAME call after a timeout or an unknown result, reuse the same key: the ledger records it once and later calls return {"status": "duplicate"} without touching cash or holdings. Only the key is compared, not the arguments — a different order (other symbol/units/price/amount) needs a new key, or it is silently treated as the retry.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.45.1Oct 19, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds the actual failure mode ('fails if the currency's cash balance is lower than the amount'), the ledger semantics (cash debited, positions untouched, inside NAV), and the human-confirmation requirement. It slightly softens the non-idempotent annotation by describing conditional safety via idempotency_key without reconciling the two, which is a minor gap rather than a contradiction.

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

Conciseness4/5

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

Front-loaded with the accounting distinction and the failure condition, then a compact Args/Returns block. The Args section duplicates schema text almost verbatim, which is mild waste, but the overall structure is easy to scan.

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

Completeness5/5

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

Covers what matters for a destructive mutation: prerequisite confirmation, the cash-balance failure condition, what is and is not affected, and idempotent retry behavior. With an output schema present it doesn't need to explain return values, though it does so briefly anyway.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented, including the enum for kind and the idempotency_key retry semantics. The Args block mostly restates the schema ('must be > 0', 'YYYY-MM-DD') and adds little syntax or format detail of its own, so the baseline 3 is appropriate.

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

Purpose5/5

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

Names a specific verb and resource ('Record a fee or a tax the user already paid') and immediately scopes the accounting effect: 'debits ledger cash, positions unchanged. It is an account cost (inside NAV), not a withdrawal.' That explicitly separates it from withdraw and from buy/sell siblings.

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

Usage Guidelines5/5

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

Gives explicit when-not guidance: trade commissions need no separate entry because buy/sell already book them, and it is not a withdrawal. It also imposes a procedural rule the agent must follow — confirm amount and date with the user before calling — which is the kind of routing detail siblings can't express.

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