Skip to main content
Glama

Fortunest demo

Trade candidates

trade_candidates
Read-onlyIdempotent

DEMO 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

NameRequiredDescriptionDefault
whyNo
sideYes
limitNo
ownedNo
driverNo
fieldsNoExtra 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.
offsetNo
symbolNo
symbolsNoNarrow to SEVERAL tickers in one call — the batch form of symbol, up to 25. The two are mutually exclusive.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare a safe read (readOnly, non-destructive, idempotent, closed-world), and the description adds substantial behavior beyond them: the synthetic shared DEMO portfolio, null rating for funds/crypto, why=true truncating at three breakdowns, null-score criteria dropping out with weights renormalizing, and the rule that candidates outside the buy-list universe are never scored. It even carries a deprecation/migration notice for the …Eur twins, which an agent would otherwise get wrong.

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

Conciseness3/5

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

The content is front-loaded and nearly every sentence carries real information, but it is delivered as one dense paragraph with stacked parentheticals and em-dashes, so the fields/why/pagination guidance is hard to locate. It is long for a read tool with a mostly self-documenting schema; some clauses (e.g. the tax-lot maturity explanation) could be tightened without loss.

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?

With no output schema, the description carries the full burden of describing the row shape (rating, reasons, plan decision, coverage, ownedEur, tax-free fields, nextMaturity, fundamentals, why breakdown) and does so in detail, including null/absence rules. For a nine-parameter analytics read tool, nothing essential to a correct call or correct interpretation of the response is missing.

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

Parameters4/5

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

Schema description coverage is only 22%, so the description must carry the load, and it does for most parameters: side's effect on the returned universe, symbol versus symbols (one ticker vs several, never one call each), fields attaching fundamentals to EVERY row, limit 1-25 default 10, and why's per-criterion payload shape including stage and renormalization. driver and owned are dismissed with a single phrase ("narrow the list"), leaving their filtering semantics thinner than the rest.

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 opening sentence states the specific verb and resource ("Read buy or sell candidates") and the required discriminator (side is buy or sell). It is also explicitly separated from the nearest sibling: "These are CANDIDATES, not orders: what to actually buy and sell, with amounts, is get_trade_plan." An agent can pick this tool without opening the schema.

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?

The description gives explicit routing: use get_trade_plan for orders/amounts, use symbols instead of one call per ticker, use fields to get fundamentals for all candidates in ONE call, and use why only with symbol or a small limit. It also names when-not conditions ("at most 3 breakdowns come back per call", why is expensive) and defines the side=buy universe versus side=sell holdings.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.