Stock Compass

Record a trade

record_trade

Destructive

Records a buy or sell the user made, as the trade form on the page does: cash, the holding, the lots and the trade journal move, and fees are what the broker charged when given, otherwise worked out from the user's trading-cost settings. Places no order with any broker. The stock has to be on the watchlist, unless add_to_watchlist is true. A buy without trigger is filed as on a signal when the stock had a buy (for an add: add or buy) signal in the last 14 days, otherwise as manual. A sale to zero closes the journal with close_reason, or "other". Sent without preview_id, it changes nothing and returns a preview of the change with a preview_id; sent again with the same arguments and that preview_id, it makes the change.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "market": "<market>",
      "ticker": "<ticker>",
      "type": "<type>",
      "price": "<price>",
      "quantity": "<quantity>"
    },
    "name": "record_trade"
  }
}

Input Schema

Name	Required	Description
`fees`	No	What the broker charged for this trade, in its currency. Without it, the fee is estimated from the user's settings.
`stop`	No	Buy only. Planned stop; null clears it.
`type`	Yes
`price`	Yes	Price per share.
`lesson`	No	Sell only. What the user took from it.
`market`	Yes	hk = Hong Kong, us = United States, cn = China A-shares.
`target`	No	Buy only. Planned target; null clears it.
`thesis`	No	Buy only. Why, in the user's words.
`ticker`	Yes	For example 0700.HK or 700 (hk), AAPL (us), 600519.SS or 600519 (cn).
`trigger`	No	Buy only. Why it was bought.
`quantity`	Yes	Shares.
`traded_at`	No	Trade date in the market; default today there, YYYY-MM-DD.
`preview_id`	No	The preview_id that the same call without it returned. Without it, nothing is changed.
`external_id`	No	The client's own id for the trade, such as the broker's order number. Sent again, it records nothing and returns the trade already recorded with it.
`close_reason`	No	Sell only.
`add_to_watchlist`	No	Buy only. true adds the stock to the watchlist before the trade when it is not on it. Default false.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 31, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already flag destructive=true and idempotent=false, and the description adds substantive behavior beyond them: automatic trigger inference from 14-day signals, automatic journal closing with close_reason or 'other', fee estimation from user settings, and the mandatory preview-then-commit handshake. It also discloses that an unconfirmed call 'changes nothing', which is exactly the safety context an agent needs before invoking a destructive tool.

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

Conciseness4/5

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

Front-loaded with the core action and side effects, and every clause carries information (no broker order, watchlist rule, signal inference, preview handshake). The sentences are long and clause-heavy, requiring a re-read, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter destructive tool with no output schema, the description covers effects, prerequisites, idempotency-adjacent behavior and the preview flow, which is close to sufficient. It leaves out auth/permission requirements and does not point to edit_trade for corrections to an already-recorded trade.

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

Parameters4/5

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

Schema coverage is 94%, so the schema carries most of the documentation burden. The description nonetheless adds derived semantics the schema cannot express: trigger is inferred as 'signal' when a buy signal occurred in the last 14 days, and close_reason falls back to 'other' when a sale zeroes the position. It does not explain interactions among buy-only fields (thesis, target, stop, lesson) beyond the schema's own 'Buy only' notes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Records a buy or sell the user made') and immediately lists the exact side effects (cash, holding, lots, journal). The explicit 'Places no order with any broker' and the watchlist precondition separate it cleanly from siblings like edit_trade, delete_trade and add_to_watchlist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear preconditions and context: the stock must be on the watchlist unless add_to_watchlist is true, and it mirrors the on-page trade form. It also spells out the two-phase call pattern (call without preview_id, then repeat with it). It never names a sibling such as edit_trade as the alternative for correcting an existing trade, so the routing is implied rather than explicit.

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

All Stock Compass tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.