OpenInvest

record_dividend

Destructive

Book dividends or interest already received by crediting ledger cash net of withholding tax; positions stay unchanged and cash is booked as account return, not a deposit.

Instructions

Record a dividend (or interest) the user already received: credits ledger cash by amount - tax_withheld, positions unchanged. It counts as account return (inside NAV), not as a deposit. Bookkeeping only — openInvest never moves money.

Confirm symbol, gross amount, withholding tax, and the date with the user before calling; this moves ledger cash. A symbol that is neither held nor in the ledger is rejected (typo guard).

Args: amount: Gross amount before withholding tax; must be > 0. currency: Currency of the cash credited. symbol: Ticker (required for dividends; optional for interest). kind: "dividend" (default) or "interest". tax_withheld: Tax withheld at source; credited cash = amount - tax_withheld. reinvest: DRIP — buy more symbol with the net amount. reinvest_price: Price per unit for the reinvestment (default: stored raw close). trade_date: YYYY-MM-DD the cash arrived (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

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

Input Schema

Name	Required	Description	Default
`kind`	No	'dividend' (default) or 'interest' (money-market / cash-account interest).	dividend
`note`	No	Free-text note stored with the ledger row.
`amount`	Yes	Gross amount before withholding tax (for kind='interest': the interest credited); must be > 0.
`symbol`	No	yfinance ticker the dividend belongs to (required for kind='dividend'; optional for interest = account-level).
`currency`	Yes	Currency the cash was credited in, e.g. 'CNY', 'USD', 'AUD'.
`reinvest`	No	DRIP: use the net cash to buy more of `symbol` (adds a second ledger row, source='drip'). The holding must exist and be in `currency`.
`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.
`tax_withheld`	No	Tax already withheld at source (kind='dividend' only); cash credited = amount - tax_withheld.
`reinvest_price`	No	Reinvestment price per unit. Omit to use the stored raw close for the date (run `backfill_raw_close` first).
`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

Behavior5/5

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

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses rich behavioral detail: exactly how cash is credited, that positions are unchanged, that it counts as account return inside NAV, that it is bookkeeping-only and never moves money, that a non-held/ledger symbol is rejected, and how the idempotency_key produces a duplicate response on retry.

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?

The description is front-loaded: the core effect appears in the first sentence, followed by a confirmation directive, then an Args block and a brief Returns note. It is somewhat long because the Args section duplicates the 100%-covered schema descriptions, but the structure remains clear and each section is purposeful.

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?

Given the tool's complexity (10 parameters, mutation with ledger effects, idempotency, reinvestment, typo guard), the description covers all necessary context. An output schema exists, so the minimal 'Returns' line is sufficient without describing return values in detail.

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 the schema already documents all ten parameters. The description largely restates those schema descriptions (e.g., amount > 0, tax_withheld formula, reinvest meaning) and adds only minor emphasis, so it does not meaningfully extend parameter semantics beyond the structured data.

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?

The first sentence states a specific verb and resource ('Record a dividend (or interest)') and immediately clarifies the accounting treatment ('credits ledger cash by amount - tax_withheld, positions unchanged'). It also distinguishes the action from a sibling concept by explicitly saying it 'counts as account return (inside NAV), not as a deposit.'

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

Usage Guidelines4/5

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

The description clearly scopes usage to dividends or interest 'the user already received' and adds a prerequisite ('Confirm symbol, gross amount, withholding tax, and the date with the user before calling'). It rules out deposit-like behavior and warns about the typo guard, but does not name or route to alternative sibling tools for other income events (e.g., record_return_of_capital).

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