OpenInvest

sell

Destructive

Records a completed broker sale in the local ledger, reducing holding units and crediting cost-currency cash; OpenInvest books the transaction and never places real orders.

Instructions

Record a sell in the local ledger: reduces the position's units (average cost unchanged) and credits cash in the holding's cost currency. Bookkeeps a trade already executed at the user's broker — openInvest never places real orders.

Confirm symbol, units, and price with the user before calling; this moves ledger cash.

Args: symbol: yfinance ticker of an existing holding. units: Quantity sold; must be > 0. price: Execution price per unit, in the holding's cost currency. idempotency_key: Reuse the same key when retrying this exact call; recorded once.

Returns: Updated position summary, or {"status": "error", "error": ...}.

Input Schema

Name	Required	Description
`price`	Yes	Execution price per unit, in the holding's cost currency.
`units`	Yes	Quantity sold; must be > 0.
`symbol`	Yes	yfinance ticker of an existing holding.
`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.

Changed1 schema field changedv0.45.1Oct 19, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "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.",
+  "title": "Idempotency Key"
+}

Addedv0.34.0Jul 24, 2026
Removedv0.31.7Jul 18, 2026
Addedv0.31.6Jul 17, 2026
Removedv0.31.5Jul 17, 2026
Changed5 schema fields changedv0.31.4Jul 17, 2026
- addedInput schema / properties / price / description
```
Added value: +"Execution price per unit, in the holding's cost currency."
```
- addedInput schema / properties / price / exclusiveMinimum
```
Added value: +0
```
- addedInput schema / properties / symbol / description
```
Added value: +"yfinance ticker of an existing holding."
```
- addedInput schema / properties / units / description
```
Added value: +"Quantity sold; must be > 0."
```
- addedInput schema / properties / units / exclusiveMinimum
```
Added value: +0
```
First observedv0.31.0Jul 16, 2026

TDQS

A4.4/5.0

Behavior5/5

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

The annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: which ledger fields change (units down, average cost unchanged, cash credited in cost currency), the warning that cash moves, and the retry/dedupe behavior of the idempotency key. No contradiction with the annotations — a fresh call with a new key legitimately sells more, consistent with idempotentHint=false.

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-loads the ledger effect and the pre-call confirmation, then organizes details under Args/Returns headings. Slightly redundant with the schema's parameter descriptions, but every section earns its place for a cash-moving mutation.

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?

For a destructive, cash-affecting mutation with an output schema present, the description covers what the tool does, what it alters, the confirmation requirement, and retry semantics. Nothing an agent needs in order to call it safely is missing, and return values needn't be expanded since the output schema exists.

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 all four parameters including idempotency_key semantics are already documented in the schema. The Args block largely restates those same definitions with no added syntax, format, or edge-case guidance. Baseline 3 is correct.

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?

States a specific verb and resource ('Record a sell in the local ledger') and immediately describes the ledger effect: reduces units with average cost unchanged, credits cash in the holding's cost currency. It also distinguishes itself from order-placing siblings by stating openInvest never places real orders, so an agent can tell it apart from place_fund_order or record_execution.

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?

Gives explicit pre-call guidance ('Confirm symbol, units, and price with the user before calling; this moves ledger cash') and scopes the tool to bookkeeping already-executed trades, which routes the agent away from real-order tools. It stops short of naming a specific sibling to use instead in ambiguous cases, so it is strong but not exhaustive.

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