Skip to main content
Glama
longsizhuo

OpenInvest

by longsizhuo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

track_asset

Idempotent

Add or update a tracked asset's symbol, investment cap, fees, target weight, and price or daily-move alerts so committee and DCA jobs cover it.

Instructions

Add a symbol to the tracked-asset list, or update an existing entry (idempotent upsert: only the fields you pass are changed). The tracked list decides which symbols the committee and DCA jobs cover. The alert_* parameters set per-asset alert lines the price sentinel checks every few minutes (price lines: 24h cooldown; day-move lines: once per trading day); each one you pass overwrites that line only. To clear a line use set_allocations with a null value. Delivery needs INVEST_EVENT_ALERT=1 on the server (default off — without it a hit is only logged to the event store, nothing is sent).

Use when the user says "track AAPL", wants to change a tracked asset's cap/channel/fees/target weight, or says "alert me when X drops below N" / "tell me if it falls 3% in a day".

Args: symbol: yfinance ticker to track (e.g. "AAPL", "0700.HK", "BTC-USD"). max_single_invest_cny: Per-decision investment cap in CNY. On a new entry it defaults to the strategy-level max_single_invest_cny; optional on update. display_name: Human-friendly name shown in reports. channel: Where the user actually buys it (broker/app name). price_offset_pct: Systematic offset between the quote and the user's actual fill price, in percent (e.g. bank gold spread). sell_fee_pct: Sell-side fee in percent, used by fee-aware math. target_pct: Target weight as a fraction of total assets in [0, 1] (read by rebalance_plan); all tracked assets' weights must sum to <= target_allocation_stock or the write is rejected. alert_price_above / alert_price_below: price lines (status.current_price basis). alert_day_drop_pct / alert_day_rise_pct: the latest daily bar's move vs the previous close, percentage points. alert_drawdown_from_cost_pct: held position below average cost, percentage points.

Returns: The stored asset entry, or {"status": "error", "error": ...}.

Input Schema

NameRequiredDescriptionDefault
symbolYesyfinance ticker to track, e.g. 'AAPL', '0700.HK', 'BTC-USD'.
channelNoWhere the user actually buys it (broker/app name).
target_pctNoTarget weight of this asset as a fraction of total assets, in [0, 1] (0.3 = 30%); read by rebalance_plan. The weights of all tracked assets must sum to <= target_allocation_stock, otherwise the write is rejected and the current sum is reported. Assets without one split the remainder equally. To clear a target use set_allocations with a null value.
display_nameNoHuman-friendly name shown in reports.
sell_fee_pctNoSell-side fee in percent, used by fee-aware math.
price_offset_pctNoSystematic offset between quote and actual fill price, in percent (e.g. bank gold spread).
alert_price_aboveNoAlert when the price reaches or exceeds this level. Same price basis as status.current_price (held: cost currency, gold booking = CNY per gram; tracked-only: the quote source's own price).
alert_price_belowNoAlert when the price falls to or below this level (same price basis as alert_price_above). Must be below alert_price_above if both are set.
alert_day_drop_pctNoAlert when the latest daily bar's drop vs the previous close reaches this many percentage points (3 = 3%, not a 0-1 fraction). On a closed market that is the last session; each trading day is reported once.
alert_day_rise_pctNoAlert when the latest daily bar's rise vs the previous close reaches this many percentage points (3 = 3%); each trading day is reported once.
max_single_invest_cnyNoPer-decision investment cap in CNY. On a new entry, defaults to the strategy-level max_single_invest_cny; optional on update.
alert_drawdown_from_cost_pctNoAlert when a held position is this many percentage points below its average cost (10 = 10%). Only evaluated for assets you hold.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.45.1
    • addedInput schema / properties / alert_day_drop_pct
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "maximum": 100,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alert when the latest daily bar's drop vs the previous close reaches this many percentage points (3 = 3%, not a 0-1 fraction). On a closed market that is the last session; each trading day is reported once.",
+  "title": "Alert Day Drop Pct"
+}
    • addedInput schema / properties / alert_day_rise_pct
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alert when the latest daily bar's rise vs the previous close reaches this many percentage points (3 = 3%); each trading day is reported once.",
+  "title": "Alert Day Rise Pct"
+}
    • addedInput schema / properties / alert_drawdown_from_cost_pct
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "maximum": 100,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alert when a held position is this many percentage points below its average cost (10 = 10%). Only evaluated for assets you hold.",
+  "title": "Alert Drawdown From Cost Pct"
+}
    • addedInput schema / properties / alert_price_above
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alert when the price reaches or exceeds this level. Same price basis as status.current_price (held: cost currency, gold booking = CNY per gram; tracked-only: the quote source's own price).",
+  "title": "Alert Price Above"
+}
    • addedInput schema / properties / alert_price_below
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alert when the price falls to or below this level (same price basis as alert_price_above). Must be below alert_price_above if both are set.",
+  "title": "Alert Price Below"
+}
    • addedInput schema / properties / target_pct
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target weight of this asset as a fraction of total assets, in [0, 1] (0.3 = 30%); read by rebalance_plan. The weights of all tracked assets must sum to <= target_allocation_stock, otherwise the write is rejected and the current sum is reported. Assets without one split the remainder equally. To clear a target use set_allocations with a null value.",
+  "title": "Target Pct"
+}
  2. Changed1 schema field changedv0.42.4
    • changedInput schema / properties / max_single_invest_cny / description
      Previous value: -"Per-decision investment cap in CNY. Required when creating a new entry; optional on update."New value: +"Per-decision investment cap in CNY. On a new entry, defaults to the strategy-level max_single_invest_cny; optional on update."
  3. Addedv0.34.0
  4. Removedv0.31.6
  5. Changed6 schema fields changedv0.31.4
    • addedInput schema / properties / channel / description
      Added value: +"Where the user actually buys it (broker/app name)."
    • addedInput schema / properties / display_name / description
      Added value: +"Human-friendly name shown in reports."
    • addedInput schema / properties / max_single_invest_cny / description
      Added value: +"Per-decision investment cap in CNY. Required when creating a new entry; optional on update."
    • addedInput schema / properties / price_offset_pct / description
      Added value: +"Systematic offset between quote and actual fill price, in percent (e.g. bank gold spread)."
    • addedInput schema / properties / sell_fee_pct / description
      Added value: +"Sell-side fee in percent, used by fee-aware math."
    • addedInput schema / properties / symbol / description
      Added value: +"yfinance ticker to track, e.g. 'AAPL', '0700.HK', 'BTC-USD'."
  6. First observedv0.31.0

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing alert cooldowns (24h for price lines, once per trading day for day-move lines), that each passed alert line overwrites only that line, the target-weight sum rejection condition, and the server-side INVEST_EVENT_ALERT=1 delivery gate that silently degrades to logging. This is exactly the kind of non-obvious operational context the description should carry.

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 purpose and usage sentences are front-loaded and earn their place, but the long Args section duplicates parameter descriptions already present at 100% schema coverage, adding bulk without new information for most fields.

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 12-parameter mutation with a full output schema, the description covers the mutation semantics, alert lifecycle, failure modes (weight-sum rejection), and the error return shape, leaving no significant gap an agent would need to guess at.

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% and the Args block largely restates the schema descriptions verbatim, so baseline 3 applies. A few additions are real ('3 = 3%, not a 0-1 fraction' caveat, overwrite-per-line behavior), but most parameter meaning is already in the structured schema.

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?

Opens with a specific verb+resource ('Add a symbol to the tracked-asset list, or update an existing entry') and immediately characterizes the operation as an idempotent upsert with per-field semantics. It clearly differentiates itself from untrack_asset and set_allocations, which it names explicitly for the clearing case.

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 concrete trigger phrases ('track AAPL', 'alert me when X drops below N', 'tell me if it falls 3% in a day') plus the update cases (cap/channel/fees/target weight). It also routes the agent elsewhere for clearing a line ('use set_allocations with a null value'), so when-to-use and when-not-to-use are both covered.

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

Deploy Server

Other Tools