TradeHub

Size a position by risk

size_position_by_risk

Read-onlyIdempotent

Turns "risk 1% of equity, stop 2% below" into a size in the base coin, rounded down to the venue step and capped by every limit (this agent's, the person's and TradeHub's). Reads equity, mark and contract rules itself: no need for get_my_account_balances or get_perp_contract_rules first. Use before every preview_perp_order. Not an order: nothing is sent. Inputs: symbol, stop_loss (USD) or stop_pct with side, risk_pct or risk_usd (default: the most allowed), venue, entry_price (default: mark), leverage. Next: preview_perp_order with the returned size_base, stop_loss and leverage.

Input Schema

Name	Required	Description	Default
`side`	No	buy = long, sell = short; needed with stop_pct
`venue`	No	Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox	hyperliquid
`symbol`	Yes	Base coin, e.g. BTC
`leverage`	No	Leverage for the margin estimate, e.g. 5
`risk_pct`	No	Loss at stop as a fraction of equity (0.01 = 1%); omitted with risk_usd also omitted: the largest your limits allow
`risk_usd`	No	Loss at stop in USD (instead of risk_pct)
`stop_pct`	No	Stop distance from entry as a fraction (0.02 = 2%), instead of stop_loss; needs side
`stop_loss`	No	Stop-loss price, USD per coin; below entry for a long, above for a short. Or give stop_pct and side instead
`entry_price`	No	Planned entry, USD per coin; omitted: the mark
`notional_usd`	No	Or the position's value in USD ("buy $200 worth"), instead of risk_pct / risk_usd; still capped by the risk limits

Output Schema

Name	Required	Description
`side`	Yes	buy (long) or sell (short), from the stop's side of entry
`venue`	Yes	Venue name
`symbol`	Yes	Base coin
`leverage`	Yes	Leverage assumed
`risk_usd`	Yes	Loss if the stop fills, USD
`capped_by`	Yes	Which limit made the size smaller than asked, if any
`size_base`	Yes	Suggested size, in the base coin (e.g. BTC), not USD, rounded down to the venue's size step; pass it to preview_perp_order as size_base
`stop_loss`	Yes	Stop-loss used, USD per coin
`equity_usd`	Yes	Equity used for the calculation (the venue's book), USD
`margin_usd`	Yes	Margin needed at the given leverage, USD
`deprecation`	No	Present only while this tool is deprecated: replacement, removal_date, changelog
`entry_price`	Yes	Entry used, USD per coin (the mark when not given)
`notional_usd`	Yes	size_base x entry, USD
`within_limits`	Yes	False if even the capped size cannot pass (e.g. below the venue minimum)
`risk_pct_of_equity`	Yes	risk_usd / equity, as a fraction

Schema Changelog

Changes observed during successful MCP inspections.

Changed63 schema fields changedNov 3, 2026
- removedInput schema / properties / entry_price / anyOf
```
Removed value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / entry_price / default
```
Removed value: -null
```
- addedInput schema / properties / entry_price / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / entry_price / title
```
Removed value: -"Entry Price"
```
- addedInput schema / properties / entry_price / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / leverage / title
```
Removed value: -"Leverage"
```
- removedInput schema / properties / notional_usd / anyOf
```
Removed value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / notional_usd / default
```
Removed value: -null
```
- addedInput schema / properties / notional_usd / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / notional_usd / title
```
Removed value: -"Notional Usd"
```
- addedInput schema / properties / notional_usd / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / risk_pct / anyOf
```
Removed value: -[
-  {
-    "exclusiveMinimum": 0,
-    "maximum": 1,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / risk_pct / default
```
Removed value: -null
```
- addedInput schema / properties / risk_pct / exclusiveMinimum
```
Added value: +0
```
- addedInput schema / properties / risk_pct / maximum
```
Added value: +1
```
- removedInput schema / properties / risk_pct / title
```
Removed value: -"Risk Pct"
```
- addedInput schema / properties / risk_pct / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / risk_usd / anyOf
```
Removed value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / risk_usd / default
```
Removed value: -null
```
- addedInput schema / properties / risk_usd / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / risk_usd / title
```
Removed value: -"Risk Usd"
```
- addedInput schema / properties / risk_usd / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / side / anyOf
```
Removed value: -[
-  {
-    "enum": [
-      "buy",
-      "sell"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / side / default
```
Removed value: -null
```
- addedInput schema / properties / side / enum
```
Added value: +[
+  "buy",
+  "sell"
+]
```
- removedInput schema / properties / side / title
```
Removed value: -"Side"
```
- addedInput schema / properties / side / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedInput schema / properties / stop_loss / anyOf
```
Removed value: -[
-  {
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / stop_loss / default
```
Removed value: -null
```
- addedInput schema / properties / stop_loss / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / stop_loss / title
```
Removed value: -"Stop Loss"
```
- addedInput schema / properties / stop_loss / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / stop_pct / anyOf
```
Removed value: -[
-  {
-    "exclusiveMaximum": 1,
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedInput schema / properties / stop_pct / default
```
Removed value: -null
```
- addedInput schema / properties / stop_pct / exclusiveMaximum
```
Added value: +1
```
- addedInput schema / properties / stop_pct / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / stop_pct / title
```
Removed value: -"Stop Pct"
```
- addedInput schema / properties / stop_pct / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedInput schema / properties / symbol / title
```
Removed value: -"Symbol"
```
- removedInput schema / properties / venue / title
```
Removed value: -"Venue"
```
- removedInput schema / title
```
Removed value: -"size_position_by_riskArguments"
```
- removedOutput schema / properties / capped_by / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / properties / capped_by / title
```
Removed value: -"Capped By"
```
- addedOutput schema / properties / capped_by / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- addedOutput schema / properties / deprecation / additionalProperties
```
Added value: +true
```
- removedOutput schema / properties / deprecation / anyOf
```
Removed value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / properties / deprecation / default
```
Removed value: -null
```
- removedOutput schema / properties / deprecation / title
```
Removed value: -"Deprecation"
```
- addedOutput schema / properties / deprecation / type
```
Added value: +[
+  "object",
+  "null"
+]
```
- removedOutput schema / properties / entry_price / title
```
Removed value: -"Entry Price"
```
- removedOutput schema / properties / equity_usd / title
```
Removed value: -"Equity Usd"
```
- removedOutput schema / properties / leverage / title
```
Removed value: -"Leverage"
```
- removedOutput schema / properties / margin_usd / title
```
Removed value: -"Margin Usd"
```
- removedOutput schema / properties / notional_usd / title
```
Removed value: -"Notional Usd"
```
- removedOutput schema / properties / risk_pct_of_equity / title
```
Removed value: -"Risk Pct Of Equity"
```
- removedOutput schema / properties / risk_usd / title
```
Removed value: -"Risk Usd"
```
- removedOutput schema / properties / side / title
```
Removed value: -"Side"
```
- removedOutput schema / properties / size_base / title
```
Removed value: -"Size Base"
```
- removedOutput schema / properties / stop_loss / title
```
Removed value: -"Stop Loss"
```
- removedOutput schema / properties / symbol / title
```
Removed value: -"Symbol"
```
- removedOutput schema / properties / venue / title
```
Removed value: -"Venue"
```
- removedOutput schema / properties / within_limits / title
```
Removed value: -"Within Limits"
```
- removedOutput schema / title
```
Removed value: -"Sizing"
```
First observedOct 27, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description still adds real context: implicit reads of equity/mark/contract rules, rounding down to the venue step, and capping by three separate limit layers (agent, person, TradeHub). It stops short of stating failure modes, e.g. what happens if stop_loss is on the wrong side of entry or a limit is zero.

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 purpose, then data-fetching, usage, exclusions, inputs and the next step – no sentence is filler. However, the parameter sentence is a dense parenthetical run-on that is harder to parse than it needs to be.

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

Completeness5/5

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

Complete for a 10-parameter computation tool: annotations cover the safety profile, the output schema covers return values, and the schema covers all parameters at 100% coverage. The description supplies what structured fields cannot – which sibling calls it obsoletes and what to do with the result.

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

Parameters3/5

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

Schema coverage is 100%, so the parameter descriptions already carry the semantics, and much of the input list here (risk_pct default being 'the most allowed', entry_price defaulting to the mark) restates it. The description does add a useful relational summary of the alternative groups (stop_loss OR stop_pct+side; risk_pct/risk_usd OR notional_usd), but that is a baseline-level contribution rather than new meaning.

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?

States a specific transformation with units and defaults: turns "risk 1% of equity, stop 2% below" into a size in the base coin. It also draws the boundary against the nearest siblings by saying it reads equity, mark and contract rules itself, so get_my_account_balances and get_perp_contract_rules are not needed first.

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

Usage Guidelines5/5

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

Explicit 'Use before every preview_perp_order' gives the trigger, and no-need-for notes name the alternatives it replaces. The next step is spelled out ('Next: preview_perp_order with the returned size_base, stop_loss and leverage'), and 'Not an order: nothing is sent' excludes a plausible misuse.

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

All TradeHub 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.

Resources

Need Help?