Trade candidates
trade_candidatesDEMO portfolio (synthetic, shared, read-only). Read buy or sell candidates. side is required (buy or sell). Each row carries one company rating (0-100, 50 neutral), its reasons, the plan decision (included/excluded/capped with reasons and amount), input coverage, and ownedEur (null when not held). A candidate the lot engine has lots for (every sell candidate, and a buy candidate that is already held) also carries taxFreeValueEur and taxFreeQty — how much of the position has already passed the holding-period test, in the display currency and in units — and nextMaturity {date, qty, valueEur}, the earliest still-future time-test date for that holding: with taxFreeValueEur 0 it is what to say instead of 'nothing', and it is absent where no open lot has a maturity date (no time test applies). All three are absent where there are no tracked lots. Funds/crypto have rating null. Legacy score is action strength, not the company rating. criteriaWeights gives the saved weights; buyCandidateSource names the buy list — side=buy holds exactly that universe (owned, starred, or both, per Settings > Trades), so a symbol outside it is not scored and has no row; side=sell is always the holdings. symbol (one ticker), symbols (SEVERAL tickers in one call — never ask once per ticker), driver and owned narrow the list. fields attaches extra fundamentals to EVERY row under fundamentals — forwardPE, peg, marketCap, fcfYield, analystUpside, fairValue and the rest — so 'forward P/E and PEG for the recommended buys' is ONE call, not one per candidate. limit is 1-25 (default 10) with offset/nextOffset. why=true is the answer to 'why is WDC scored 72': every item then also carries why, the per-criterion breakdown the Trades tab's score expander shows — criterion, label, raw (in unit), weight, the 0-100 score, contribution (its points: the contributions add up to the rating) and one sentence from the engine, plus stage — the earnings stage that splits Quality and Valuation between their profit rows and growth readings. One the data could not support has score null and applied false — it drops out and the remaining weights renormalize rather than counting as zero. why is expensive, so pass symbol (or a small limit) with it: at most 3 breakdowns come back per call. These are CANDIDATES, not orders: what to actually buy and sell, with amounts, is get_trade_plan. Each '…Eur' field now also ships under its currency-neutral name (amountEur→amount, buyEur→buy, valueEur→value, totalEur→totalAmount); the '…Eur' twins are DEPRECATED and will be removed — read the neutral name.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"side": "<side>"
},
"name": "trade_candidates"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| why | No | ||
| side | Yes | ||
| limit | No | ||
| owned | No | ||
| driver | No | ||
| fields | No | Extra fundamentals to attach to EVERY candidate in the answer, under `fundamentals`: name, sector, industry, price, marketCap, forwardPE, trailingPE, peg, fcfYield, earningsGrowth, revenueGrowth, returnOnEquity, profitMargins, dividendYield, targetMeanPrice, analystUpside, shortPercentOfFloat, fairValue, fairValueUpsidePct. | |
| offset | No | ||
| symbol | No | ||
| symbols | No | Narrow to SEVERAL tickers in one call — the batch form of symbol, up to 25. The two are mutually exclusive. |