OpenInvest is a self-hosted, multi-agent AI investment decision engine that provides auditable financial analysis, portfolio tracking, and strategy management — without ever placing real orders.
Portfolio & Market Data (Read-Only)
status — View a full portfolio snapshot: cash balances, holdings, live prices, and unrealized P&L
live_prices — Fetch live market backdrop: spot gold (USD/CNY), USDCNY, AUDCNY, NDQ.AX, VIX, and 10-year Treasury yield
what_if — Simulate hypothetical price moves (e.g. "what if Nasdaq drops 10%?") against current holdings
history — Retrieve recent trade records and committee verdict history
Strategy & Decision Auditing (Read-Only)
strategy — View target stock/cash allocation, tracked assets, and long-term insights
decisions — Get the full decision ledger: verdicts, rule interventions, user adoption/refusal, and post-hoc outcomes
explain_decision — Audit the full 4-role debate transcript and CIO memo behind any specific committee verdict
discipline — View the discipline ledger: HOLD ratio, intercepted impulsive trades, and counterfactual savings
Ledger Management (Write)
buy / sell — Record trades in the local ledger (bookkeeping only, not real orders)
deposit / withdraw — Record cash movements in the ledger
Strategy Configuration (Write)
set_allocations — Update target stock/cash allocation ratio
track_asset / untrack_asset — Add, update, or remove symbols from the tracked-asset list (investment cap, fees, channel)
AI Committee & Event Ingestion (Write)
run_committee — Trigger the 4-role LLM investment committee (Macro Strategist, Quant Analyst, Risk Officer, CIO) on any ticker to produce a BUY/ACCUMULATE/HOLD/TRIM/SELL verdict with full reasoning
record_execution — Log whether you followed or declined a committee verdict, closing the adoption-rate feedback loop
ingest_event — Feed a finance news article into the event ledger for committee RAG recall and analysis
Integrates with Hermes Agent as a plugin, allowing Hermes to leverage OpenInvest's multi-agent investment committee and auditable decision trails.
A self-hosted investment decision engine built for modern AI agents. Multi-agent information isolation and cross-challenge protocol, providing an auditable decision trail (Audit Trail).
📚 Full Architecture Wiki · 🇨🇳 中文版
OpenInvest is a self-hosted investment decision engine built for modern AI agents.
It provides a verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records. Instead of replacing Claude Code, Codex, Hermes, or OpenClaw, OpenInvest is designed to power them.
Related MCP server: Fund Dashboard MCP Server
Benchmark Portfolio: The system introduces 8 standard control benchmarks across 4 quadrants (AI advisors / Mutual funds / Wealth management / Broad market index). For details on the comparison methodology and data cleaning logic, see docs/wiki/README.md.
System Self-Disclosure: This system is an auditing tool to eliminate human investment cognitive biases and enforce reasoning transparency, not a return-amplifying black box. Latest automated audit (docs/verdict_accuracy.md): Directional verdicts (excluding HOLD) have a true hit rate of 42.2% (n=56, below random); HOLD accounts for 56% of all decisions. The system's value lies in transparency and discipline (mostly staying inactive, low turnover), not directional prediction. Detailed log stream can be found in docs/verdict_accuracy.md.
This project systematically attempts to falsify its own edge and publishes negative results as-is. The deterministic features the committee reads, and the timing signals around them, were tested against pre-registered statistical gates — none survived as tradable alpha.
Test | Result | Verdict |
Q1 cross-sectional stock picking | 6 features, mean-IC 0.025–0.067, Holm-corrected p=0.397 | No significant stock-picking signal |
M1 multivariate GBM (out-of-sample) | mean OOS IC +0.003, p=0.925 | Feature combination doesn't help either — no signal |
Q2 gold MA200 trend | p_holm=0.016, significant — but | Statistically significant, economically untradable |
Per-asset multi-signal families | 3 assets × 4 signal families × parameter grid = 24 variants per asset; after costs + DSR deflation, none passes DSR > 0.95 | No tradable signal in any family |
Positive control | A cheating perfect-foresight timing signal scores DSR = 1.00 | The harness can detect a real signal |
Methodology: Newey-West HAC t-statistics, Deflated Sharpe Ratio (Bailey & López de Prado 2014, re-derived equation by equation), Holm correction, zero lookahead, and LLM training-cutoff probes.
Details: experiments/signal-eval/README.md · docs/verdict_accuracy.md · ADR-022 · ADR-023
Most AI investment assistants try to become better chatbots. OpenInvest instead builds a transparent, verifiable, and auditable decision engine that plugs into personal agents such as Claude Code, Codex, Hermes, and OpenClaw — every improvement in those agents automatically makes OpenInvest more capable.
The division of labor is deliberate: your agent handles long-term memory, natural conversation, and user understanding; OpenInvest handles the verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records.
User
│
┌───────────┴───────────┐
▼ ▼
Your Agent OpenInvest
(User Understanding) (Market Understanding)
│ │
└───────────┬───────────┘
▼
Better Investment DecisionsYour agent knows you. OpenInvest knows investing.
OpenInvest intentionally avoids "owning" the user. Most AI products try to own everything—memory, persona, chat history, and workspaces. OpenInvest takes a back seat. It exposes clean APIs, CLI commands, and agent skills (Claude Code / Codex / Hermes / OpenClaw), letting your primary agent manage the conversation and context while OpenInvest powers the underlying investment intelligence.
Multi-Agent Investment Committee: Isolated analysis and round-rebuttal debate.
Coordinator-Worker Architecture: Prevents context contamination and role hallucination.
Information Isolation: Rigidly blocks quant and risk analysts from out-of-boundary contexts.
Auditable Decision Trail: Clean logs showing exactly "why" each decision was made.
Markdown-as-a-Database: Frontmatter (YAML) + Markdown (Body) as the single source of truth.
Long-Horizon Backtesting: Built-in test harness with lookahead bias protections.
Dreaming-Based Memory Consolidation: Nightly memory distillation to prevent context drift.
Self-Hosted / Zero-Cost: Powered directly by your local agent's reasoning resources.
Agent Skill: Lightweight plugin for Claude Code / Codex / Hermes / OpenClaw, with interactive bootstrap wizard.
Automated Deployment: GitHub Actions workflow to run the committee and email reports daily.
Add the lightweight skill from your agent's plugin registry. The host agent will automatically pull the core code and align dependencies on first run:
# Claude Code
/plugin marketplace add longsizhuo/openInvest
/plugin install invest@openinvest
# Codex
codex plugin marketplace add longsizhuo/openInvest
# Hermes Agent
hermes plugins install longsizhuo/openInvest --enable
# OpenClaw
openclaw plugins install clawhub:openinvestAny other MCP client: register the MCP server from step 2 below (full walkthrough in the agent tutorial).
The backend ships on PyPI; ~/openInvest holds only your data:
# MCP (18 tools, any MCP client; add --http for a remote streamable-HTTP server — BETA)
claude mcp add openinvest -e INVEST_HOME=~/openInvest -- uvx openinvest-mcp
# or plain CLI
INVEST_HOME=~/openInvest uvx openinvest statusSend set up invest (or 帮我初始化 invest) to any skill-enabled AI terminal. The system will trigger an interactive bootstrap wizard to guide you through:
Detecting the memory/ state storage path and .env configuration.
5-dimensional profiling (Legal name, Risk capacity, Debt structure, Initial holdings, and optional keys).
Running static data migration to immediately generate your first asset exposure memo.
💡 Zero-Cost Execution: In skill interactive mode, the committee's underlying reasoning relies entirely on the host agent's (e.g. Claude Code) reasoning pipeline. No third-party API Key is consumed. You only need to configure an API key when setting up automated crons or calling independent Web APIs.
For self-hosting details, see docs/QUICK_START.md. (The bundled Web GUI was retired on 2026-07-05 — all capabilities are exposed via CLI/MCP; a standalone frontend may return later.)
Run the committee automatically via GitHub Actions and receive daily digest emails.
⚠️ Fork must be set to Private: State files (holdings, verdicts) will be committed back to your fork. Public forks will leak your private financial information.
Fork this repository and change its visibility to Private (Settings -> Visibility).
Run set up invest locally to generate the initial memory/ folder, then commit and push it to your private fork:
git add -f memory/ && git commit -m "chore: init memory state" && git pushIn your fork's Settings -> Secrets and variables -> Actions, add the following Secrets:
LLM_API_KEY (or DEEPSEEK_API_KEY): API key to run the committee.
EMAIL_SENDER / EMAIL_PASSWORD: Gmail address + App Password.
DIGEST_EMAIL_TO: Recipient email address.
Enable Workflows under the Actions tab. The workflow runs automatically at 10:00 AM (Beijing time) daily; you can also manually trigger daily-report via Run workflow.
openInvest does not run a mock debate in a single LLM session. The system enforces an Information Isolation Contract at the core/committee/ layer, orchestrating 4 independent LLM processes in a directed acyclic graph (DAG):
[ Macro Data Injection ]
│
▼ 1. Macro Alignment Context
┌──────────────────────────┐
│ Macro Strategist │ (VIX / Interest rate spread / Currency momentum)
└─────────────┬────────────┘
│
▼ 2. Async Multi-Dimensional Scrutiny (Async DAG)
┌─────────────┴────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Quant Analyst │ │ Risk Officer │
│ (RSI / Momentum) │ │ (Concentration) │
│ │ │ │
│ 🛑 No Holdings │ │ 🛑 No Indicators │
└─────────┬────────┘ └─────────┬────────┘
│ │
└─────────────┬─────────────┘
│
▼ 3. Round 2 Rebuttal & Cross-Challenge
│ Mutual feedback loop for signal correction
▼
┌──────────────────────────────────────────────┐
│ Chief Investment Officer (CIO) │
└───────────────────────┬──────────────────────┘
│
▼ 4. Deterministic State Persistence
[ BUY / ACCUMULATE / HOLD / TRIM / SELL ]Macro Strategist: Assesses the global macro landscape (VIX, yield curve spread, core currency matrix) to establish the portfolio's risk threshold.
Quant Analyst: A pure mathematical momentum and technical indicator filter. Strictly blocked from knowing portfolio holdings to eliminate human attachment and loss-aversion biases.
Risk Officer: Focuses entirely on tail risks (drawdown buffers, concentration limits, solvency multipliers). Strictly blocked from technical indicators to make objective asset exposure rulings.
Round 2 Rebuttal: Quant and Risk analysts are fed each other's Round 1 reports in Round 2, challenging boundaries until signals converge or safety valves trigger.
CIO (Chief Investment Officer): Synthesizes the audited reports and outputs a structured Verdict (BUY / ACCUMULATE / HOLD / TRIM / SELL) with a confidence level. No auto-order execution occurs; final action remains strictly up to the human auditor.
Key trade-offs behind this design are recorded as ADRs in docs/wiki/adr/ (24 to date), including rulings that overturned our own earlier designs — ADR-007 retired the few-shot CIO route, and ADR-009 rejected TA-style analyst agents after a pre-registered experiment.
Coordinator-Worker Pattern: Workers operate in isolated namespaces. Boundary constraints are hardcoded at the framework layer in Python to prevent attention contamination in large multi-role prompts.
Markdown-as-a-Database: The system uses Frontmatter (YAML) + Markdown (Body) as the single source of truth. Leveraging fcntl.flock process file locks and temporary atomic file replacement, it provides a tamper-proof investment audit trail natively tracked by Git.
Three-Phase Dreaming Consolidation: Distills daily decisions against actual market outcomes nightly (Light Sleep $\rightarrow$ REM $\rightarrow$ Deep Sleep) to consolidate long-term insights, preventing Large Language Model (LLM) context drift over long execution spans.
The system defaults to DeepSeek endpoints and supports any standard OpenAI-compatible API. LLM provider setup and all tunable runtime overrides (ADR-017) are documented in docs/wiki/22-configuration.md.
No Financial Advice: This system is a decision-support tool powered by LLMs. Output memos represent simulated reasoning based on deterministic data and do not constitute asset allocation advice.
Backtest Time-Lock & Lookahead Guard: The backtest engine (scripts/backtest_runner.py) has a hardcoded safety valve: it rejects backtests for decision_date > 2024-06-30 by default (override with --allow-lookahead). Since mainstream foundation models have training cutoff dates around mid-2024, backtesting on later intervals introduces severe Lookahead Bias (model pre-training leakage). Parameter tuning, Optuna sweeps, and prompt optimization must run strictly on historical windows prior to June 30, 2024.
MiMo — Special thanks to MiMo Quantitative Lab for sponsoring production-grade high-performance LLM inference (powering mimo-v2.5-pro long-horizon sweeps).
OpenClaw Dreaming Guide — Theoretical foundation for the three-phase sleep-cycle memory distillation framework.
This project is licensed under the MIT License - see the LICENSE file for details.
Add an RSS/Atom feed to the crawler's source list. The URL is live-probed before saving — a URL that doesn't parse as a feed is rejected. Idempotent: re-adding an existing URL returns the existing entry. Capped so the list can't grow unbounded.
Use when someone says "follow 's news" / "加个新闻源".
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | RSS/Atom feed URL (a real feed, not a webpage). | |
| name | Yes | Short slug for the feed, [a-z0-9_] (e.g. 'wsj_markets'). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations: live-probing before saving, idempotency (consistent with idempotentHint=true), and a cap on list size. Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces this without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the primary action. Subsequent sentences add essential behavioral and usage details without redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 params, simple input schema, and output schema present), the description is fully adequate. It covers purpose, behavior, and usage guidelines. The output schema handles return values, so no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds value by explaining the live-probing behavior for the 'url' parameter, which is not in the schema description. The 'name' parameter is already well-described in the schema as a 'Short slug' with regex pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add an RSS/Atom feed to the crawler's source list.' It uses a specific verb and resource, and distinguishes from sibling 'remove_news_source' (removal) and 'news_sources' (likely listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage cues: 'Use when someone says "follow <site>'s news" / "加个新闻源".' This helps the agent match user intent. It does not explicitly mention when not to use or alternatives, but the sibling context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a buy in the local ledger: adds to an existing position with weighted-average cost, or opens a new position for an unseen symbol. This bookkeeps a trade the user already placed with their broker — openInvest never places real orders.
Confirm symbol, units, and price with the user before calling; this moves ledger cash.
Args:
symbol: yfinance ticker (e.g. "AAPL", "510300.SS", "GC=F").
units: Quantity bought; must be > 0.
price: Execution price per unit, in currency.
currency: Currency of price (default "CNY").
kind: Asset kind tag, e.g. "equity", "etf", "commodity".
unit_label: Human display label for units (default "股", i.e. shares).
Returns: Updated position summary, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Asset kind tag, e.g. 'equity', 'etf', 'commodity'. | equity |
| price | Yes | Execution price per unit, in `currency`. | |
| units | Yes | Quantity bought; must be > 0. | |
| symbol | Yes | yfinance ticker, e.g. 'AAPL', '510300.SS', 'GC=F'. | |
| currency | No | Currency of `price`, e.g. 'CNY', 'USD', 'AUD'. | CNY |
| unit_label | No | Human display label for units (default '股', i.e. shares). | 股 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits: weighted-average cost, new position opening, ledger cash movement, and no real orders. Annotations (destructiveHint=true) are consistent and description adds richer context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose first, then behavior, instructions, args, returns. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: parameter descriptions, return values (updated position summary or error), and behavioral constraints. Adequate for a complex tool with 6 params and 3 required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value beyond schema with examples (e.g., yfinance ticker formats), default values, and parameter explanations (e.g., unit_label default '股').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it records a buy in the local ledger, adding to existing positions or opening new ones. The verb 'buy' is specific and distinguishes from sibling tools like 'sell'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to confirm symbol, units, and price with user before calling, and clarifies this is bookkeeping, not a real order. Lacks explicit when-not-to-use but is implied by context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the unified decision ledger: every committee verdict joined with rule interventions, the user's actual executions or refusals (with reasons), and post-hoc outcome data — plus an adoption-rate summary.
Answers "how often did I follow the advice", "which recommendations did I skip", and "what did the safety rules rewrite". Read-only.
Args: days: Look-back window in days (default 90).
Returns:
Object with count, summary (adoption rate and aggregates), and
decisions (list; each entry has decision_id, verdict, confidence,
intervention, executed flag, matched trades, and outcome).
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds value by declaring 'Read-only' and detailing the return shape (count, summary, decisions with fields). This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, uses a clear structure with a purpose statement, answering summary, and then explicit args/returns. Every sentence is informative with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (1 optional param) and presence of an output schema (though not shown), the description fully covers what the tool returns and its purpose, making it complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the parameter info ('Look-back window in days (default 90)') which is already in the schema. No extra meaning is added, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('unified decision ledger'), and clearly distinguishes from siblings like 'explain_decision' by framing it as a ledger of all decisions with adoption summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what questions the tool answers ('how often did I follow the advice', etc.), providing clear context for its use. However, it does not explicitly state when not to use it or mention alternatives like 'explain_decision'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a cash deposit into the ledger, in any currency. Bookkeeping only — no real payment system is connected.
Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to add; must be > 0.
Returns: Updated cash balances, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Amount to add; must be > 0. | |
| currency | Yes | ISO-style currency code, e.g. 'CNY', 'USD', 'AUD'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set destructiveHint=true, but the description describes adding funds, which is not destructive. This is a contradiction; description does not resolve it or explain any destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Relatively concise with clear sections for args and returns, though the docstring format adds some redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, and return format. With output schema present, it's sufficient for a simple tool, but the annotation contradiction decreases trust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds only marginal clarification (e.g., 'must be > 0'). No significant added meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Record a cash deposit into the ledger', specifies the resource (cash deposit), and distinguishes from siblings like withdraw, buy, sell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states this is bookkeeping-only with no real payment, implying it's a simulated deposit. Implicitly tells when to use (adding cash) vs not (withdrawing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the committee's discipline ledger: how often it chose inaction (HOLD ratio), how many impulsive user trades its rules intercepted, and the counterfactual money saved/lost by those interventions (ADR-023: the system's proven value is discipline and transparency, not alpha).
Use when the user asks "what has the committee blocked" or "is this tool actually helping". Read-only.
Returns:
Object with summary (structured stats) and markdown (the same
ledger pre-rendered for direct display to the user).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so description adds value by detailing return structure (summary + markdown) and the specific metrics computed. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste. Front-loaded purpose, then usage, then return structure. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, read-only annotation, and existence of an output schema, the description fully explains what the tool returns and its purpose without needing more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in input schema (100% coverage), so baseline is 4. Description does not need to add param info; it correctly focuses on behavior and return format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get' and resource 'discipline ledger', specifying exact metrics (HOLD ratio, intercepted trades, money saved/lost). Distinguishes from siblings like 'decisions' and 'explain_decision' by focusing on blocked interventions and counterfactual value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: when user asks 'what has the committee blocked' or 'is this tool actually helping'. Also marks as 'Read-only', which implies it should not be used for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full reasoning behind one committee verdict: the complete 4-role debate transcript with the CIO memo, plus the path-probability snapshot the CIO saw at decision time.
Use when the user asks "why was today's verdict HOLD" or wants to audit a past decision. Read-only.
Args:
decision_id: "/", e.g. "2026-07-03/GC=F" — exactly as
returned in the decisions tool output.
Returns:
Object with verdict, confidence, alloc_cny, transcript_markdown
(render this to the user), and path_snapshot (may be null).
| Name | Required | Description | Default |
|---|---|---|---|
| decision_id | Yes | "<date>/<symbol>", e.g. "2026-07-03/GC=F" — exactly as returned by the decisions tool. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description reinforces read-only behavior and details the return object fields, including that path_snapshot may be null. It could mention error handling for invalid decision_id, but overall adds useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose, usage guidance, parameter details, return object. Every sentence is necessary and concise without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and an output schema, the description covers all essential aspects: what the tool does, when to use it, how to construct the argument, and what the response contains. It also includes a behavioral note about rendering transcript_markdown.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description reiterates the parameter format. It adds value by specifying the exact origin of the decision_id from the 'decisions' tool, which is meaningful beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Get the full reasoning behind one committee verdict' and details the output components (transcript, memo, path snapshot). It distinguishes this tool from siblings by focusing on a single decision's comprehensive reasoning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when the user asks "why was today's verdict HOLD" or wants to audit a past decision.' Also provides the specific source of the decision_id from the 'decisions' tool and marks the operation as read-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recent trade records and committee verdict history.
Use when the user asks "what did I buy recently" or "what did the committee decide lately". Read-only.
Args: n: Maximum number of recent trades to return (default 10).
Returns:
Object with trades (each with symbol, direction, units, price,
timestamp, status) and recent committee verdict records.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Maximum number of recent trades to return. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds the read-only label and details the return structure (trades with specific fields and committee verdict records), providing useful behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. Every sentence adds value, and the docstring style for Args and Returns is well-structured without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no nested objects) and the existence of an output schema, the description is sufficiently complete. It outlines what is returned without needing to detail the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'n' already described as 'Maximum number of recent trades to return.' The description repeats this and adds no additional semantics, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'the most recent trade records and committee verdict history.' It uses a specific verb ('Get') and resource, and distinguishes itself from siblings like 'live_prices' or 'status' by focusing on historical data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage context with example queries like 'what did I buy recently' and notes it is read-only. It does not explicitly mention when not to use or suggest alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Feed a finance news item you (the host agent) found into the event ledger. The backend LLM normalizes it, grades severity, maps affected symbols, and stores it for committee RAG recall.
You have far better search reach than the self-hosted crawler (including Chinese-language sources) — proactively feed news relevant to the user's holdings, especially A-share/regional coverage the crawler misses. Idempotent: re-sending the same url or claim does not double-insert. Requires a backend LLM key.
Args:
title: Headline of the news item.
url: Canonical source URL (also the dedup key).
snippet: Short excerpt or summary of the article body.
source: Publisher name (e.g. "Reuters") — the news outlet.
published_at: ISO 8601 publication time, if known.
ingested_by: Your own agent identity (e.g. "hermes") for provenance;
distinct in meaning from source.
Returns: Ingestion result with the normalized event id(s) and dedup status.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Canonical source URL (also the dedup key). | |
| title | Yes | Headline of the news item. | |
| source | No | Publisher name (e.g. 'Reuters') — the news outlet. | |
| snippet | No | Short excerpt or summary of the article body. | |
| ingested_by | No | Your own agent identity (e.g. 'hermes') for provenance; distinct from source. | host-agent |
| published_at | No | ISO 8601 publication time, if known. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds context beyond these: it requires a backend LLM key, normalizes content, grades severity, maps symbols, and discusses idempotency regarding URLs. This adds meaningful behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement, usage guidance, idempotency note, and parameter list. It is front-loaded with purpose. Slightly verbose in repeating some schema details, but overall concise for the amount of information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters (2 required) and an output schema, the description covers all essentials: what happens during ingestion, dedup behavior, requirements (LLM key), and return value. It provides sufficient context for the agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats parameter info and adds minor clarifications (e.g., 'ingested_by distinct from source'), but does not significantly enhance understanding beyond the schema. It does not introduce new constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Feed a finance news item... into the event ledger.' It specifies the verb (feed/ingest), resource (event ledger), and outcome (normalization, grading, etc.). It distinguishes from sibling tools like news_sources or run_committee by focusing on ingesting new items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use: 'You have far better search reach... proactively feed news... especially A-share/regional coverage the crawler misses.' It implies the alternative of relying on the self-hosted crawler and gives context for agent action. No explicit 'when not to use' but sufficient for a high score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a one-shot market backdrop: spot gold (USD/oz and CNY/gram), USDCNY and AUDCNY FX rates, the NDQ.AX ETF price, the VIX volatility index, and the 10-year US Treasury yield (TNX).
Use for quick market context before analysis or when the user asks "how is the market / what's the gold price". Read-only; single batch, no arguments.
Returns:
Object keyed by instrument (GC_F_usd_per_oz, gold_cny_per_gram_spot,
USDCNY, AUDCNY, NDQ_AX, VIX, TNX) plus as_of ISO timestamp. A field
is null when its upstream quote is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. Description adds that it's a single batch fetch, lists exact instruments, and notes null values when unavailable. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear listing of instruments and null handling. Slightly verbose but every sentence adds value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, but description still lists return keys and notes null behavior. Complete for a zero-parameter, read-only batch fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; description confirms no arguments needed. Schema coverage is 100% (empty schema). Baseline for 0 params is 4, but description adds clarity by stating 'no arguments'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches a one-shot market backdrop with specific instruments (gold, FX, ETF, VIX, TNX). Distinguishes from siblings which are trading/account tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'Use for quick market context before analysis or when the user asks how is the market / what's the gold price'. Notes read-only, single batch, no arguments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the news feed sources the crawler pulls from: the built-in default feeds plus user-added extra feeds. Extra feeds can be added/removed with add_news_source / remove_news_source; defaults are fixed.
Use when someone asks "what news sources do you follow" or before adding/removing a source.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds context about built-in vs extra feeds and mentions related mutating tools, which is helpful but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and resource, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and zero parameters, the description fully explains what the tool returns (list of sources with types). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% (empty). Description correctly omits param details, as none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'list' and resource 'news feed sources', clearly distinguishing between built-in defaults and user-added extras. References sibling tools add_news_source and remove_news_source to differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: when someone asks 'what news sources do you follow' or before adding/removing a source. Provides clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record whether the user executed or declined a committee verdict, with their reason. Appends to the execution ledger; idempotent — replaying the same record is a no-op, so retries are safe.
Call when the user says "I bought it / I didn't buy / I disagree". When
they decline, ask one short question for the reason first — this closes
the adoption-rate loop that decisions reports on.
Args:
decision_id: "/" from the decisions output.
executed: True if the user acted on the verdict, False if declined.
reason: The user's stated reason (especially when declined).
trade_ids: Optional trade record IDs to link explicitly.
Returns: The stored execution record, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | The user's stated reason (especially when declined). | |
| executed | Yes | True if the user acted on the verdict, False if they declined. | |
| trade_ids | No | Optional trade record IDs to link explicitly. | |
| decision_id | Yes | "<date>/<symbol>" from the decisions tool output. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description complements the annotations by explaining the idempotent behavior: 'replay the same record is a no-op, so retries are safe'. It also notes that the tool appends to the execution ledger and returns the stored record or error, providing full behavioral disclosure beyond the annotations' flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence states purpose, then behavioral note, usage guidance, Args, and Returns. Every sentence serves a purpose, and the structure is easy to parse. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (2 required), an output schema, and annotations, the description covers all necessary context: purpose, when to call, how to handle edge cases (decline), parameter details, and return value format. It is complete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the format of `decision_id` ("<date>/<symbol>") and the context for `reason` (especially when declined). While the Args section is somewhat redundant with the schema, it provides a clear, contextual listing that helps the agent understand parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Record' and the resource 'execution of committee verdict'. It distinguishes itself by specifying the scope (whether the user executed or declined) and mentions idempotency and retry safety, which are unique traits among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-call scenarios: 'when the user says "I bought it / I didn't buy / I disagree"'. It also gives specific guidance for the decline case: ask one short question for the reason first, referencing the sibling tool `decisions` and the adoption-rate loop.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a user-added news feed by name or URL. Built-in default feeds cannot be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Feed name or URL to remove (extra feeds only; defaults can't be removed). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true). The description adds specific behavioral context: only user-added feeds can be removed, default feeds are protected. This goes beyond the annotation's binary flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main purpose, followed by a key limitation. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's function and main constraint for a simple delete operation. With an output schema present, return values are not needed. Minor gap: no mention of behavior for non-existent keys or confirmation requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the 'key' parameter that already specifies it can be a feed name or URL and excludes defaults. The tool description adds no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Remove' and resource 'user-added news feed', clearly distinguishing from sibling tools like add_news_source and news_sources. It also explicitly states that built-in default feeds cannot be removed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description indicates when to use (remove user-added feeds) and when not (defaults cannot be removed). It provides clear context but does not explicitly name alternative tools for adding or listing feeds, though those are implied by sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the 4-role LLM investment committee on a symbol (Direct path): Macro Strategist, Quant Analyst, and Risk Officer debate from isolated evidence, then a CIO synthesizes one calibrated BUY/HOLD/SELL-style verdict with a written memo.
Requires a backend LLM key (e.g. DEEPSEEK_API_KEY) and takes 30-90s on
a cache miss. If the symbol was already analyzed today, the cached
verdict is returned instantly unless force is set. Decision support
only — the human always executes.
Args: symbol: Any yfinance ticker (US / HK / A-share / ETF / crypto / commodities), e.g. "AAPL", "GC=F", "510300.SS". force: Re-run even if a verdict already exists for today. max_rounds: Cross-challenge debate rounds (default 1).
Returns:
Object with decision_id, cached flag, and verdict (verdict,
confidence, suggested allocation, CIO memo).
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Re-run even if a verdict already exists for today. | |
| symbol | Yes | Any yfinance ticker (US / HK / A-share / ETF / crypto / commodities), e.g. 'AAPL', 'GC=F', '510300.SS'. | |
| max_rounds | No | Cross-challenge debate rounds. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotent, not readonly), the description adds details: requires backend key, 30-90s cache miss, instant cache hit, and returned object fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with sections, but slightly verbose. Each sentence adds value; could be trimmed modestly but remains clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (4 roles, debate, caching, output schema), the description covers prerequisites, parameter details, performance, and return structure. Output schema exists but description still usefully summarizes fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description enhances parameters with examples ('AAPL', 'GC=F'), clarifies force behavior, and explains max_rounds as 'Cross-challenge debate rounds.' Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Run') and resource ('4-role LLM investment committee on a symbol'), clearly distinguishing it from siblings like buy/sell which execute trades.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (for investment analysis), mentions prerequisites (backend LLM key), and states 'Decision support only — the human always executes.' It does not explicitly contrast with alternatives but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Returns: Updated position summary, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is destructive (reduces units, moves cash) and requires user confirmation, aligning with the destructiveHint annotation. It adds nuanced context about ledger movement and the absence of real order placement, going beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single paragraph explaining purpose and caution, followed by clearly labeled arguments and return value. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers behavior, parameters, preconditions, return type, and limitations (no real orders). With the presence of an output schema and the annotations, the description is fully complete and leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (100% coverage). The description repeats these descriptions verbatim without adding new constraints or clarifications, so it does not add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record a sell' and resource 'local ledger', explains the effects (reduces units, credits cash), and distinguishes from real trading by noting 'openInvest never places real orders'. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for bookkeeping an already executed trade, not for placing orders. It also mandates user confirmation before calling. However, it does not explicitly contrast with the sibling tool 'buy' or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the strategy's target stock/cash allocation ratio. The two values must sum to ≈1.0; schema validation rejects and rolls back any write that would corrupt the strategy file.
Use when the user says e.g. "set my target to 70% stock / 30% cash".
Args: target_allocation_stock: Stock weight in [0, 1], e.g. 0.7. target_allocation_cash: Cash weight in [0, 1], e.g. 0.3.
Returns: The updated allocation, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| target_allocation_cash | Yes | Cash weight in [0, 1], e.g. 0.3. Must sum to ~1.0 with stock. | |
| target_allocation_stock | Yes | Stock weight in [0, 1], e.g. 0.7. Must sum to ~1.0 with cash. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and not destructive. Description adds that schema validation rejects and rolls back corrupting writes, providing behavioral safety context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient use of words: one introductory paragraph, bulleted args, return description. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter semantics, behavioral traits, and return value. No gaps given the tool's simplicity and presence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. Description adds concrete example (0.7, 0.3) and restates the sum constraint, adding slight extra value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update the strategy's target stock/cash allocation ratio' with specific verb and resource. Includes constraint that values must sum to ~1.0 and schema validation ensures safety. Distinguishes from sibling 'decisions' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage example ('set my target to 70% stock / 30% cash'). Could benefit from mentioning when not to use or alternatives, but example is sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a full snapshot of the user's portfolio: cash balances per currency, every holding with units / average cost / live price, and unrealized P&L per position and in total.
Use when the user asks "show my portfolio", "how is my P&L", or before proposing any trade. Read-only; fetches live quotes, so values change between calls.
Returns:
Object with cash (currency → amount), holdings (list of positions
with symbol, units, avg_cost, live price, market value, pnl_pct), and
portfolio-level totals.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds that it fetches live quotes and values change between calls, plus details on returns. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: scope, usage, output. No filler, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no params and output schema exists; description explains output structure in enough detail for an agent to understand what it returns. Fully covers needed context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (0 params, 100% schema coverage). Description adds no param info, but none needed. Baseline 4 for no-param tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a full snapshot of the user's portfolio' and lists specific contents (cash, holdings, P&L). Distinguishes from siblings like history and live_prices by being a comprehensive overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when the user asks "show my portfolio", "how is my P&L", or before proposing any trade.' Also notes it's read-only. Lacks explicit when-not or direct sibling differentiation, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the user's investment strategy: target stock/cash allocation, the list of tracked assets (per-asset investment cap, purchase channel, fee settings), and long-term insights distilled by the nightly Dreaming memory-consolidation job.
Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking". Read-only.
Returns:
Object with target_allocation (stock/cash ratios), target_assets
(tracked symbols with constraints), and insights (distilled
lessons from past decisions).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. The description adds context about the return value structure and the nightly Dreaming job, enhancing transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with clear sections and bullet points, though slightly verbose. Every sentence adds value, making it effective without being overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an existing output schema, the description fully covers the tool's purpose, usage, and return structure. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the user's investment strategy, including target allocation, tracked assets, and insights. This distinguishes it from sibling tools like set_allocations, track_asset, and untrack_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking".' Also marks as read-only, differentiating from mutating tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Use when the user says "track AAPL" or wants to change a tracked asset's cap/channel/fees.
Args: symbol: yfinance ticker to track (e.g. "AAPL", "0700.HK", "BTC-USD"). max_single_invest_cny: Per-decision investment cap in CNY. Required when creating a new entry; 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.
Returns: The stored asset entry, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | yfinance ticker to track, e.g. 'AAPL', '0700.HK', 'BTC-USD'. | |
| channel | No | Where the user actually buys it (broker/app name). | |
| display_name | No | Human-friendly name shown in reports. | |
| sell_fee_pct | No | Sell-side fee in percent, used by fee-aware math. | |
| price_offset_pct | No | Systematic offset between quote and actual fill price, in percent (e.g. bank gold spread). | |
| max_single_invest_cny | No | Per-decision investment cap in CNY. Required when creating a new entry; optional on update. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Idempotent upsert behavior is clearly stated and matches annotation (idempotentHint=true). Gives extra detail: 'only the fields you pass are changed', and notes that 'max_single_invest_cny' is required on create but optional on update. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and idempotency, then usage case, then parameter list. Every sentence adds value; no fluff. Well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully explains the tool's purpose, behavior, parameter details, and return format (stored asset entry or error). Output schema is present, so return values are covered. Complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all parameters (100% coverage), but the description adds context beyond schema: e.g., explains that 'max_single_invest_cny' is required on creation and optional on update, and clarifies the purpose of 'channel' and 'price_offset_pct'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Add a symbol to the tracked-asset list, or update an existing entry'. Distinguishes from sibling 'untrack_asset' by being an upsert, not a removal. Provides context that tracked list decides coverage for committee and DCA jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when the user says "track AAPL" or wants to change a tracked asset's cap/channel/fees.' Implies not for removal (since 'untrack_asset' sibling exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a symbol from the tracked-asset list — the committee and DCA jobs stop covering it. Holdings and trade history are untouched; schema validation guarantees at least one tracked asset remains.
Args: symbol: yfinance ticker currently in the tracked list.
Returns: The updated tracked list, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | yfinance ticker currently in the tracked list. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds critical context: holdings and trade history are untouched, and schema guarantees at least one tracked asset remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs, no redundancy, and front-loaded with the main action. Very efficient, though the Args and Returns could be integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, good annotations, and mention of output schema, the description covers effects, safety, validation, and error handling fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the 'symbol' parameter. The description repeats the same info without adding new meaning, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Remove', 'stop covering') and clearly identifies the resource ('tracked-asset list'). It distinguishes itself from the sibling 'track_asset' and other trading tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the action and notes a validation constraint (at least one asset remains), but does not explicitly provide when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate portfolio P&L for a hypothetical price move: "what happens to my portfolio if moves ±pct% / reaches ". Pure arithmetic over current holdings — no LLM call, instant, free.
Use when the user asks scenario questions like "if the Nasdaq drops 10%,
how much do I lose". Provide exactly one of pct or price.
Args: symbol: yfinance ticker held or tracked by the user (e.g. "NDQ.AX", "GC=F", "510300.SS"). pct: Hypothetical percent change, e.g. -10 for a 10% drop. price: Hypothetical absolute target price (alternative to pct).
Returns: Object with the position's simulated value change and the resulting portfolio-level P&L delta.
| Name | Required | Description | Default |
|---|---|---|---|
| pct | No | Hypothetical percent change, e.g. -10 for a 10% drop. Provide exactly one of pct or price. | |
| price | No | Hypothetical absolute target price (alternative to pct). | |
| symbol | Yes | yfinance ticker held or tracked by the user, e.g. 'NDQ.AX', 'GC=F', '510300.SS'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description adds significant behavioral context: 'pure arithmetic over current holdings — no LLM call, instant, free.' It clarifies the tool has no side effects, is fast, and free, which goes well beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a short intro, usage guidance, parameter explanations, and return description. It is front-loaded with the key purpose and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 3 parameters, an output schema exists, and the description covers purpose, usage, parameters, and returns, it is fully complete. Additional details like 'instant, free' provide useful context. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description adds value by reiterating the mutual exclusivity constraint 'Provide exactly one of pct or price' and clarifying the symbol parameter as 'yfinance ticker held or tracked by the user' beyond the schema's description. This earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Simulate portfolio P&L for a hypothetical price move' and distinguishes it from siblings by emphasizing it is a pure arithmetic simulation with no LLM call, instant, and free. This specificity and differentiation from tools like buy/sell/track earns a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use: 'when the user asks scenario questions like "if the Nasdaq drops 10%, how much do I lose"' and provides clear guidance on parameters: 'Provide exactly one of pct or price.' While it does not explicitly state when not to use, the context makes it clear for hypotheticals, so it earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a cash withdrawal from the ledger, in any currency. Fails if the balance is insufficient. Bookkeeping only — no real payment system is connected.
Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to remove; must be > 0.
Returns: Updated cash balances, or {"status": "error", "error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Amount to remove; must be > 0. | |
| currency | Yes | ISO-style currency code, e.g. 'CNY', 'USD', 'AUD'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that it is bookkeeping only (no real payment system) and fails on insufficient balance, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs. The first sentence states the purpose, and the second adds constraints. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, no nested objects, output schema exists), the description covers the return values, constraints, and caveats sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description's Args section largely mirrors the schema descriptions. It does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Record a cash withdrawal from the ledger, in any currency,' specifying the verb and resource. It distinguishes from siblings like 'deposit' and 'buy' by focusing on cash withdrawal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (record cash withdrawal) and includes a condition ('Fails if balance is insufficient'), but it does not explicitly compare with alternatives like 'sell' or 'deposit'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.34.0add_news_sourcebuydepositdisciplineexplain_decisionhistoryingest_eventlive_pricesnews_sourcesrecord_executionremove_news_sourcerun_committeesellstatusstrategytrack_assetuntrack_assetwhat_ifwithdrawv0.31.7buydisciplineexplain_decisioningest_eventlive_pricesrecord_executionsellset_allocationswhat_ifv0.31.6historyrun_committeeselltrack_assetuntrack_assetv0.31.5depositsellset_allocationsstatusstrategywithdrawv0.31.4buy8 fields changedInput schema / properties / currency / descriptionAdded value: +"Currency of `price`, e.g. 'CNY', 'USD', 'AUD'."Input schema / properties / kind / descriptionAdded value: +"Asset kind tag, e.g. 'equity', 'etf', 'commodity'."Input schema / properties / price / descriptionAdded value: +"Execution price per unit, in `currency`."Input schema / properties / price / exclusiveMinimumAdded value: +0Input schema / properties / symbol / descriptionAdded value: +"yfinance ticker, e.g. 'AAPL', '510300.SS', 'GC=F'."Input schema / properties / unit_label / descriptionAdded value: +"Human display label for units (default '股', i.e. shares)."Input schema / properties / units / descriptionAdded value: +"Quantity bought; must be > 0."Input schema / properties / units / exclusiveMinimumAdded value: +0decisions1 field changedInput schema / properties / days / descriptionAdded value: +"Look-back window in days."deposit3 fields changedInput schema / properties / amount / descriptionAdded value: +"Amount to add; must be > 0."Input schema / properties / amount / exclusiveMinimumAdded value: +0Input schema / properties / currency / descriptionAdded value: +"ISO-style currency code, e.g. 'CNY', 'USD', 'AUD'."explain_decision1 field changedInput schema / properties / decision_id / descriptionAdded value: +"\"<date>/<symbol>\", e.g. \"2026-07-03/GC=F\" — exactly as returned by the decisions tool."history1 field changedInput schema / properties / n / descriptionAdded value: +"Maximum number of recent trades to return."ingest_event6 fields changedInput schema / properties / ingested_by / descriptionAdded value: +"Your own agent identity (e.g. 'hermes') for provenance; distinct from source."Input schema / properties / published_at / descriptionAdded value: +"ISO 8601 publication time, if known."Input schema / properties / snippet / descriptionAdded value: +"Short excerpt or summary of the article body."Input schema / properties / source / descriptionAdded value: +"Publisher name (e.g. 'Reuters') — the news outlet."Input schema / properties / title / descriptionAdded value: +"Headline of the news item."Input schema / properties / url / descriptionAdded value: +"Canonical source URL (also the dedup key)."record_execution4 fields changedInput schema / properties / decision_id / descriptionAdded value: +"\"<date>/<symbol>\" from the decisions tool output."Input schema / properties / executed / descriptionAdded value: +"True if the user acted on the verdict, False if they declined."Input schema / properties / reason / descriptionAdded value: +"The user's stated reason (especially when declined)."Input schema / properties / trade_ids / descriptionAdded value: +"Optional trade record IDs to link explicitly."run_committee4 fields changedInput schema / properties / force / descriptionAdded value: +"Re-run even if a verdict already exists for today."Input schema / properties / max_rounds / descriptionAdded value: +"Cross-challenge debate rounds."Input schema / properties / max_rounds / minimumAdded value: +1Input schema / properties / symbol / descriptionAdded value: +"Any yfinance ticker (US / HK / A-share / ETF / crypto / commodities), e.g. 'AAPL', 'GC=F', '510300.SS'."sell5 fields changedInput schema / properties / price / descriptionAdded value: +"Execution price per unit, in the holding's cost currency."Input schema / properties / price / exclusiveMinimumAdded value: +0Input schema / properties / symbol / descriptionAdded value: +"yfinance ticker of an existing holding."Input schema / properties / units / descriptionAdded value: +"Quantity sold; must be > 0."Input schema / properties / units / exclusiveMinimumAdded value: +0set_allocations6 fields changedInput schema / properties / target_allocation_cash / descriptionAdded value: +"Cash weight in [0, 1], e.g. 0.3. Must sum to ~1.0 with stock."Input schema / properties / target_allocation_cash / maximumAdded value: +1Input schema / properties / target_allocation_cash / minimumAdded value: +0Input schema / properties / target_allocation_stock / descriptionAdded value: +"Stock weight in [0, 1], e.g. 0.7. Must sum to ~1.0 with cash."Input schema / properties / target_allocation_stock / maximumAdded value: +1Input schema / properties / target_allocation_stock / minimumAdded value: +0track_asset6 fields changedInput schema / properties / channel / descriptionAdded value: +"Where the user actually buys it (broker/app name)."Input schema / properties / display_name / descriptionAdded value: +"Human-friendly name shown in reports."Input schema / properties / max_single_invest_cny / descriptionAdded value: +"Per-decision investment cap in CNY. Required when creating a new entry; optional on update."Input schema / properties / price_offset_pct / descriptionAdded value: +"Systematic offset between quote and actual fill price, in percent (e.g. bank gold spread)."Input schema / properties / sell_fee_pct / descriptionAdded value: +"Sell-side fee in percent, used by fee-aware math."Input schema / properties / symbol / descriptionAdded value: +"yfinance ticker to track, e.g. 'AAPL', '0700.HK', 'BTC-USD'."untrack_asset1 field changedInput schema / properties / symbol / descriptionAdded value: +"yfinance ticker currently in the tracked list."what_if3 fields changedInput schema / properties / pct / descriptionAdded value: +"Hypothetical percent change, e.g. -10 for a 10% drop. Provide exactly one of pct or price."Input schema / properties / price / descriptionAdded value: +"Hypothetical absolute target price (alternative to pct)."Input schema / properties / symbol / descriptionAdded value: +"yfinance ticker held or tracked by the user, e.g. 'NDQ.AX', 'GC=F', '510300.SS'."withdraw3 fields changedInput schema / properties / amount / descriptionAdded value: +"Amount to remove; must be > 0."Input schema / properties / amount / exclusiveMinimumAdded value: +0Input schema / properties / currency / descriptionAdded value: +"ISO-style currency code, e.g. 'CNY', 'USD', 'AUD'."v0.31.0buydecisionsdepositdisciplineexplain_decisionhistoryingest_eventlive_pricesrecord_executionrun_committeesellset_allocationsstatusstrategytrack_assetuntrack_assetwhat_ifwithdrawScored across 21 tools
Each tool serves a distinct function: strategy allocation, asset tracking, cash operations, trade recording, committee decisions, news management, etc. No two tools have overlapping purposes; descriptions clearly delineate responsibilities.
Tool names follow a consistent verb-first pattern (e.g., set_allocations, track_asset, record_execution). Even single-word verbs like buy/sell fit naturally. No mixing of conventions or confusing variations.
21 tools cover a broad domain (strategy, portfolio, committee, news) without feeling bloated. Each tool earns its place, though the count is slightly above the typical ideal range. Still well-scoped for the server's purpose.
The tool surface covers CRUD for assets, cash, trades, and strategy, plus committee operations and news ingestion. Minor gaps exist (e.g., no direct rebalancing or order execution), but these are intentional design choices.
Portfolio analytics + US-equity market research for AI clients. ChatGPT deep-research compat.
Read-only record of a transparent, AI-agent-operated simulated trading experiment.
Trade journal plus read-only market, research, and brokerage data tools for external AI clients.
Investment research superagent: podcasts, SEC filings, and no-code research pipelines.
