Equibles

Add Portfolio Lot

AddPortfolioLot

Record a user-confirmed purchase or sale in the caller's portfolio. Never infer or guess the instrument, quantity, price or date. For stock, pass ticker; a listing on another exchange is its MIC:TICKER symbol (e.g. XPAR:AIR, as ScreenStocks returns it). For an option, pass both its underlying ticker and verified OCC symbol; unknown or expired contracts are rejected. quantity is signed: positive for long shares/contracts, negative for short stock or written options. costPerUnit is always the positive per-share price or option premium, never the per-contract total, in the currency the listing trades in and in major units (London prices in pounds, not pence). Identical retries within the duplicate window return the existing lot instead of adding another.

Input Schema

Name	Required	Description
`note`	No	Optional. A short note from the user about this lot, up to 256 characters.
`fxRate`	No	Optional. The broker's exchange rate on the trade, as units of the portfolio's currency per 1 unit of the stock's trading currency (e.g. 0.92 for EUR per USD). Only when the user states it; omit to convert at the official rate on the trade date.
`ticker`	Yes	Stock ticker, or MIC:TICKER for a listing on another exchange, e.g. XPAR:AIR. For an option, the UNDERLYING U.S. ticker, e.g. AAPL.
`quantity`	Yes	Signed size: shares for a stock, contracts for an option. Negative for a short sale or a written option.
`portfolio`	Yes	The portfolio to add to, by name.
`costPerUnit`	Yes	Price per share, always positive: paid for a long, received for a short. For an option, the premium per share (a $3.20 contract is 3.20, not 320). In the currency the stock trades in, in major units: London prices in pounds, not pence.
`acquiredDate`	Yes	The trade date, as yyyy-MM-dd. Cannot be in the future.
`optionContract`	No	Optional. The OCC option symbol, e.g. O:AAPL260724C00110000. Provide it to record an option contract; omit it for shares.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 11, 2026

changedInput schema / properties / costPerUnit / description

Previous value: -"Price per share, always positive: paid for a long, received for a short. For an option, the premium per share (a $3.20 contract is 3.20, not 320)."New value: +"Price per share, always positive: paid for a long, received for a short. For an option, the premium per share (a $3.20 contract is 3.20, not 320). In the currency the stock trades in, in major units: London prices in pounds, not pence."

changedInput schema / properties / ticker / description

Previous value: -"Stock ticker. For an option, the UNDERLYING ticker, e.g. AAPL."New value: +"Stock ticker, or MIC:TICKER for a listing on another exchange, e.g. XPAR:AIR. For an option, the UNDERLYING U.S. ticker, e.g. AAPL."

Changed1 schema field changedOct 11, 2026

addedInput schema / properties / fxRate

Added value: +{
+  "default": null,
+  "description": "Optional. The broker's exchange rate on the trade, as units of the portfolio's currency per 1 unit of the stock's trading currency (e.g. 0.92 for EUR per USD). Only when the user states it; omit to convert at the official rate on the trade date.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

AddedAug 18, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds real behavioral detail beyond that: unknown or expired option contracts are rejected, and identical retries inside the duplicate window return the existing lot instead of creating another. That idempotency disclosure materially changes how an agent should retry.

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?

The core action and the no-guessing rule are front-loaded, and nearly every sentence carries a distinct rule (symbol format, signed quantity, price convention, currency units, idempotency). It is a dense single block, however, so the option/stock and currency rules are harder to scan than they need to be.

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 an 8-parameter mutation tool with no output schema and no parent annotations beyond safety hints, the description covers validation behavior, currency handling, and duplicate-window semantics well. It does not describe permissions/authorization or what the successful response contains beyond the duplicate-retry case.

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 100%, so the baseline is 3, but the description adds cross-cutting meaning the schema states only piecewise: quantity is signed (negative for short/written), costPerUnit is always the positive per-share/per-contract premium and never the per-contract total, and prices are in the listing's currency in major units (pounds not pence).

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

Purpose5/5

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

The description opens with a specific verb+resource+scope: 'Record a user-confirmed purchase or sale in the caller's portfolio.' It also implicitly separates itself from UpdatePortfolioLot/ClosePortfolioLot by framing the action as recording a new buy/sell rather than amending or closing an existing lot.

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?

It gives strong precondition guidance ('Never infer or guess the instrument, quantity, price or date') and per-instrument guidance (ticker for stock, underlying ticker + verified OCC symbol for options). It stops short of naming alternatives for correcting or removing an existing lot (UpdatePortfolioLot / RemovePortfolioLot).

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

All Equibles tools Inspect

Try in Browser