Enables trading of perpetual futures on the Solana blockchain through Jupiter Perpetuals, providing tools for market data retrieval, portfolio management, and executing leveraged positions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jupiter Perps MCP Server Show my current open positions and total unrealized PnL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that enables AI agents to trade perpetual futures on Jupiter Perpetuals (Solana).
⚠️ DISCLAIMER This software is provided for educational and research purposes only. Trading perpetual futures involves substantial risk of loss and is not suitable for all investors. You are solely responsible for any trading decisions and losses incurred. The authors and contributors assume no liability for your use of this software. Use at your own risk with funds you can afford to lose.
Market Data: Real-time prices, 24h statistics, and historical OHLCV candles
Portfolio Management: View USDC balance, open positions, PnL, and fees
Position Trading: Open, increase, and close leveraged positions (1.1x - 100x)
Fee Estimation: Calculate trading costs before execution
Transaction Safety: Automatic compute budget optimization and simulation
Supported assets: SOL, ETH, BTC
Related MCP server: Hyperliquid MCP Server
Jupiter Perpetuals uses an oracle-based pricing model with a shared liquidity pool:
Pricing: Trades execute at oracle prices (Signal/Chainlink/Pyth), not order book prices
Liquidity: You trade against a pool of SOL, ETH, WBTC, USDC, USDT (not against other traders)
Slippage Protection: MAX_SLIPPAGE_BPS protects against oracle price movement during transaction execution
Fees:
Base trading fee + Price impact fee (protects liquidity providers)
Hourly borrow fees (instead of traditional funding rates)
This means large trades don't suffer from order book depth issues, but oracle price slippage can still occur if prices move during transaction confirmation.
Position Model: Positions are identified by asset + side (e.g., "Long SOL"). You can only have one position per asset/side pair. The protocol automatically merges any additional opens into the existing position, increasing its size and adjusting entry price.
Collateral: All positions use USDC as collateral. For long positions, the protocol swaps USDC to the asset internally.
Fees: Trading fees (base + price impact) are paid when opening/increasing/closing positions. Borrow fees accrue hourly and are settled when modifying/closing. Use estimate_open_position before trading to understand total costs.
Trading: All trades execute at market price immediately (no limit orders). Tools return a transaction signature for logging purposes. The protocol processes positions asynchronously in a separate transaction - this may take a few seconds and can fail. Use get_account_portfolio to verify the position was successfully created.
Node.js 18+
A Solana wallet with USDC for trading
Wallet private key (base58 encoded)
git clone <repository-url>
cd jupiter-perps-mcp
npm install
npm run buildCreate a .env file:
cp .env.example .envRequired settings:
WALLET_PRIVATE_KEY=your_base58_encoded_private_key
RPC_URL=https://api.mainnet-beta.solana.comOptional settings:
MAX_SLIPPAGE_BPS=200 # Default: 200 (2%)
PRIORITY_FEE_MICRO_LAMPORTS=100000 # Default: 100000Quick verification with MCP inspector:
npx @modelcontextprotocol/inspector node dist/index.jsCreate .mcp.json in your project directory:
{
"mcpServers": {
"jupiter-perps": {
"command": "node",
"args": ["/absolute/path/to/jupiter-perps-mcp/dist/index.js"]
}
}
}Or use ${workspaceFolder} for relative paths:
{
"mcpServers": {
"jupiter-perps": {
"command": "node",
"args": ["${workspaceFolder}/jupiter-perps-mcp/dist/index.js"]
}
}
}Run the MCP server as an HTTP service to isolate sensitive wallet keys from Claude Code. The wallet private key stays on the host machine, while Claude Code runs in a separate environment and can only trade through MCP tools.
1. On the host machine (with wallet access), configure .env:
MCP_PORT=3000 # HTTP server port (default: 3000)2. Start in HTTP mode:
npm run start:remoteOr set MCP_MODE=http in .env for deployment/automation.
3. In your sandboxed Claude Code environment, create .mcp.json:
{
"mcpServers": {
"jupiter-perps": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}For different machines, replace localhost with the host IP (e.g., http://192.168.1.100:3000/mcp).
Security: The server binds to localhost by default. For remote access, use SSH tunneling, VPN, or firewall rules to control access.
4. Test the connection:
curl http://localhost:3000/healthTool | Description |
| Current market prices, 24h stats, fees, and liquidity |
| Historical OHLCV data (5m, 15m, 1h, 4h, 1d, 1w) |
| USDC balance, positions, PnL, and fees to close |
| Calculate fees and resulting position before trading |
| Open or increase a leveraged position |
| Close an existing position at market price |
Tool | Description |
| RSI momentum oscillator (0-100, >70 overbought, <30 oversold) |
| MACD trend and momentum indicator |
| Bollinger Bands volatility and mean reversion indicator |
| ATR volatility measure for stop-loss placement |
| Exponential Moving Average (faster than SMA) |
| Simple Moving Average (classic trend indicator) |
| Stochastic momentum oscillator (0-100, >80 overbought, <20 oversold) |
⚠️ Important Safety Notes
Never commit your .env file
Use a dedicated wallet with limited funds
All positions use USDC as collateral
Review transaction details before confirming
Consider using a private RPC endpoint for production
MIT
Submits a transaction to fully close an existing position at market price. The protocol processes asynchronously (may take a few seconds) - use get_account_portfolio to verify closure. Returns transaction signature (for logging) and confirmation message. Collateral is returned as USDC.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset of the position to close | |
| side | Yes | The side of the position to close |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the asynchronous processing nature ('may take a few seconds'), the verification method needed, what gets returned ('transaction signature and confirmation message'), and what happens to collateral ('returned as USDC'). This covers important operational aspects beyond basic functionality.
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 efficiently structured with three sentences that each serve distinct purposes: stating the core action, explaining processing behavior and verification, and describing return values and collateral outcome. There's no wasted text, and important information is 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?
For a mutation tool with no annotations and no output schema, the description does well by explaining the asynchronous nature, verification requirements, return values, and collateral handling. However, it could be more complete by mentioning potential errors, rate limits, or authentication requirements that might be relevant for this financial transaction 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?
With 100% schema description coverage, the input schema already fully documents both parameters (asset and side) with their enums and descriptions. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline expectation but doesn't enhance parameter understanding.
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 specific action ('fully close an existing position at market price') and resource ('position'), distinguishing it from sibling tools like 'open_position' (which creates positions) and 'get_account_portfolio' (which reads positions). It goes beyond just restating the name by specifying the execution method and outcome.
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 on when to use this tool ('to fully close an existing position') and explicitly references an alternative tool for verification ('use get_account_portfolio to verify closure'). However, it doesn't explicitly state when NOT to use it or compare it to all possible alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimates fees and resulting position state for opening a new position or increasing an existing one. Returns: (1) fees_to_pay - fees for THIS trade only: open fee, price impact fee, and any accrued borrow fees that will be settled; (2) resulting_position - final state AFTER trade: weighted average entry price, total size, total collateral, leverage, and liquidation price. Does NOT execute the trade. Important: total_collateral_usd includes protocol-specific factors beyond visible fees: (a) USDC price typically ~$0.9997-1.0003, not exactly $1.00; (b) Long positions incur additional swap costs (~0.05%) when converting USDC to the borrowed asset; (c) rounding/slippage. Short positions generally match calculations more closely as they borrow USDC directly. Note: The Jupiter protocol returns slightly lower leverage than requested, with larger differences at higher leverage (e.g., 10x → 9.99x, 100x → 99.47x).
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset to trade | |
| side | Yes | Direction of the trade | |
| collateral_amount | Yes | Amount of USDC to use as collateral (minimum: 10 USD, must be <= wallet balance) | |
| leverage | Yes | Leverage multiplier (added size = collateral * leverage) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers comprehensive behavioral disclosure. It explains what the tool returns (fees_to_pay and resulting_position with detailed breakdowns), warns about protocol-specific factors affecting calculations (USDC price variance, swap costs for long positions, rounding/slippage), and discloses Jupiter protocol's leverage approximation behavior. This goes well beyond basic functionality description.
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 appropriately sized and front-loaded with the core purpose. Every sentence adds value: first states purpose and returns, second clarifies non-execution, third explains protocol-specific factors, fourth details differences between long/short positions, fifth discloses leverage approximation. While comprehensive, it could be slightly more concise in the protocol factors section.
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 complexity of financial position estimation with no annotations and no output schema, the description provides exceptional completeness. It thoroughly explains what the tool returns, behavioral characteristics, protocol-specific nuances, and important caveats. This gives the agent sufficient context to understand the tool's behavior and limitations despite the absence of structured output documentation.
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 the baseline is 3. The description adds significant value by explaining how parameters interact with the estimation: it clarifies that 'collateral_amount' is in USDC and mentions minimum requirements, and it explains how 'leverage' affects calculations ('added size = collateral * leverage') and the protocol's approximation behavior. However, it doesn't provide additional context for 'asset' or 'side' beyond what the schema already documents.
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 specific action ('Estimates fees and resulting position state') and distinguishes it from execution ('Does NOT execute the trade'). It explicitly differentiates from the sibling 'open_position' tool by emphasizing this is a simulation/preview tool rather than an execution 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?
The description provides explicit guidance on when to use this tool: for estimating fees and position state 'for opening a new position or increasing an existing one.' It clearly distinguishes from the sibling 'open_position' by stating 'Does NOT execute the trade,' and the context of fee/state estimation before actual execution is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves wallet's current USDC balance, total equity, and all open positions. For each position returns: asset, side (Long/Short), collateral, equity, size, entry price, mark price, leverage, liquidation price, and fees_to_close (accrued borrow fees that will be settled, estimated close fee, estimated price impact).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the data returned but does not address critical aspects like whether this is a read-only operation, potential rate limits, authentication requirements, or error conditions. For a financial data tool, this omission is significant.
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 a single, dense sentence that front-loads the core purpose and efficiently lists all returned data points. Every element (balance, equity, positions with detailed fields) earns its place without redundancy, making it highly concise and 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?
Given the complexity (financial portfolio data) and lack of annotations or output schema, the description is moderately complete. It thoroughly explains the return values but misses behavioral context like safety or performance traits. This is adequate for a read operation but leaves gaps in operational guidance.
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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on output semantics, detailing the returned data structure (e.g., positions with fields like asset, side, equity). This adds value beyond the schema, though a baseline of 4 is set for zero-parameter tools.
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 specific verb ('retrieves') and resource ('wallet's current USDC balance, total equity, and all open positions'), distinguishing it from siblings like get_candles (market data) or get_market_snapshot (market overview). It precisely defines what data is returned, making the purpose 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 no guidance on when to use this tool versus alternatives like get_market_snapshot or other indicator tools. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer usage based on the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves historical OHLCV (Open, High, Low, Close, Volume) pricing data for trend analysis and technical analysis. Returns candle data with timestamps (unix seconds), open/high/low/close prices, and volume. Minimum 3 candles required.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol to retrieve candles for | |
| interval | Yes | Candle interval/timeframe | |
| limit | Yes | Number of candles to retrieve (minimum 3, maximum 500). Use 50-100 for recent analysis, 200+ for historical patterns. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return format (OHLCV with timestamps) and a behavioral constraint ('minimum 3 candles required'), but lacks details on permissions, rate limits, error conditions, or data freshness, which are important for a data retrieval tool.
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 front-loaded with the core purpose, followed by return details and a key constraint, all in three concise sentences with zero wasted words, making it easy to scan and understand.
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 data retrieval tool with no annotations and no output schema, the description covers the basic purpose and return format adequately but lacks completeness in areas like error handling, pagination, or example usage, which would help an agent use it correctly in complex scenarios.
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 the baseline is 3. The description adds value by specifying the data format (OHLCV with unix timestamps) and reinforcing the 'minimum 3 candles' constraint, which complements the schema's limit parameter (min 10, max 500), though it doesn't fully explain the discrepancy.
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 with specific verbs ('retrieves historical OHLCV pricing data') and resources ('candle data'), and distinguishes it from siblings by focusing on raw price data retrieval rather than indicators, positions, or snapshots.
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 implies usage for 'trend analysis and technical analysis,' which provides some context, but it does not explicitly state when to use this tool versus alternatives like get_market_snapshot or indicator tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate ATR (Average True Range) - measures volatility for stop-loss placement and position sizing. Higher ATR = higher volatility. Returns suggested stop-loss levels at 1x, 2x, 3x ATR below current price. Common periods: 10, 14, 20.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| period | Yes | ATR period (5-50). Common: 10, 14, 20 | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by explaining what the tool returns (suggested stop-loss levels at 1x, 2x, 3x ATR below current price) and providing practical context about higher ATR indicating higher volatility. It doesn't cover error conditions, rate limits, or authentication needs, but gives substantial 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 perfectly concise with three sentences that each earn their place: first explains what ATR is and its purpose, second explains the volatility relationship, third describes the return values and common periods. No wasted words, front-loaded with core 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?
For a calculation tool with no annotations and no output schema, the description does well by explaining what the tool returns (stop-loss levels) and providing practical usage context. It could be more complete by specifying the exact format of the return values or error conditions, but covers the essential behavioral aspects given the 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some value by mentioning common periods for the 'period' parameter (10, 14, 20) and explaining the tool's purpose, but doesn't provide additional semantic context beyond what's in the schema descriptions.
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 specific verb 'calculate' and resource 'ATR (Average True Range)', explaining it measures volatility for stop-loss placement and position sizing. It distinguishes from sibling tools by focusing on ATR specifically, unlike other indicators like RSI or MACD.
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 for when to use this tool: for measuring volatility to inform stop-loss placement and position sizing. It mentions common periods (10, 14, 20) as guidance but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Bollinger Bands - measures volatility and identifies overbought/oversold conditions. Returns upper band, middle (SMA), and lower band. Price touching upper band suggests overbought, lower band suggests oversold. Common settings: (20,2) standard, (20,1.5) tight, (20,2.5) wide.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| period | Yes | Period for middle band SMA (5-50). Common: 20 | |
| std_dev | Yes | Standard deviation multiplier (0.5-4.0). Common: 1.5 (tight), 2.0 (standard), 2.5 (wide) | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly describes what the tool returns (three bands) and offers interpretation guidance (price touching bands suggests conditions). However, it doesn't disclose important behavioral aspects like whether this requires real-time data access, potential rate limits, error conditions, or how historical data is sourced. The description adds value but leaves gaps in operational transparency.
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 efficiently structured with zero wasted words. The first sentence states purpose and returns, the second provides interpretation guidance, and the third offers practical parameter settings. Every sentence earns its place, and information is appropriately front-loaded with the core functionality stated first.
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 technical indicator calculation tool with 5 parameters and no output schema, the description provides adequate context about what's calculated and how to interpret results. However, without annotations and with no output schema, it should ideally describe the return format more explicitly (e.g., data structure, timestamps, calculation methodology). The common settings guidance helps but doesn't fully compensate for the lack of output documentation.
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 the schema already documents all parameters thoroughly. The description adds minimal parameter semantics by mentioning common settings (20,2 standard; 20,1.5 tight; 20,2.5 wide) which partially overlaps with schema descriptions. It doesn't add significant meaning beyond what's already in the well-documented 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 tool calculates Bollinger Bands, specifies what it returns (upper band, middle SMA, lower band), and explains its purpose for measuring volatility and identifying overbought/oversold conditions. It distinguishes from siblings like get_indicator_rsi or get_indicator_macd by focusing specifically on Bollinger Bands analysis.
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 about when Bollinger Bands are useful (measuring volatility, identifying overbought/oversold conditions) and offers common parameter settings guidance. However, it doesn't explicitly state when to use this tool versus alternative indicators like RSI or MACD from the sibling list, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate EMA (Exponential Moving Average) - a trend indicator that reacts faster to price changes than SMA. Price above EMA suggests uptrend, below suggests downtrend. Common periods: 9, 20, 50, 100, 200.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| period | Yes | EMA period (2-200). Common: 9, 20, 50, 100, 200 | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only partially discloses behavioral traits. It explains what EMA is and how to interpret it, but doesn't mention computational characteristics, data sources, latency, error conditions, or rate limits. For a calculation tool with no annotations, this leaves significant behavioral gaps.
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 appropriately sized with three sentences that each add value: defines EMA, explains interpretation, and lists common periods. It's front-loaded with the core purpose. Could be slightly more concise by integrating the period information more efficiently.
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 calculation tool with 4 parameters and 100% schema coverage but no output schema or annotations, the description is moderately complete. It explains what EMA is and how to interpret results, but doesn't describe the return format, calculation methodology, or error handling. The lack of output schema means the description should ideally explain what values are returned.
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%, providing good documentation for all parameters. The description adds minimal value beyond the schema - it mentions common periods (9, 20, 50, 100, 200) which are already in the period parameter description, but doesn't provide additional semantic context about parameter interactions or calculation specifics.
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 calculates EMA (Exponential Moving Average), specifying it's a trend indicator that reacts faster than SMA and explains its interpretation (price above/below EMA suggests uptrend/downtrend). This distinguishes it from sibling tools like get_indicator_sma by highlighting the faster reaction time and providing interpretation guidance.
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 implies usage for trend analysis by explaining how to interpret EMA values, but doesn't explicitly state when to use this tool versus alternatives like SMA or other indicators. It mentions common periods which suggests typical use cases, but lacks explicit guidance on tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate MACD (Moving Average Convergence Divergence) - identifies trend direction and momentum. Returns MACD line, signal line, and histogram. Histogram crossing zero indicates trend changes. Common settings: (12,26,9) standard, (5,13,5) fast/scalping, (19,39,9) slow/swing.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| fast_period | Yes | Fast EMA period (2-50). Must be less than slow_period. | |
| slow_period | Yes | Slow EMA period (2-50). Must be greater than fast_period. | |
| signal_period | Yes | Signal line period (2-20). Common: 9 | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adequately describes what the tool returns (MACD line, signal line, histogram) and the significance of histogram crossings, but doesn't mention computational characteristics (e.g., performance, rate limits), error conditions, or data freshness. The description doesn't contradict any annotations since none exist.
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 efficiently structured in three sentences: purpose statement, return values with interpretation, and practical parameter guidance. Every sentence adds value with no wasted words, and the most important information (what MACD is and what it returns) comes first.
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 calculation tool with 6 parameters and no output schema, the description provides good context about returns and parameter usage. However, without annotations or output schema, it could benefit from more detail about the return format (e.g., data structure, units) and any limitations. The description compensates well for the lack of output schema by explaining what values are returned.
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 the schema already documents all parameters thoroughly. The description adds value by providing common parameter settings (12,26,9 for standard, 5,13,5 for fast/scalping, 19,39,9 for slow/swing) which gives practical guidance beyond the schema's technical ranges. However, it doesn't explain the relationship between parameters or provide additional syntax details.
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 calculates MACD (Moving Average Convergence Divergence) and identifies its purpose as analyzing trend direction and momentum. It distinguishes from sibling tools like get_indicator_rsi or get_indicator_sma by specifying the MACD indicator specifically, and mentions the three return components (MACD line, signal line, histogram).
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 about when MACD is used (identifying trend direction and momentum, with histogram crossing zero indicating trend changes) and offers common parameter settings for different trading strategies (standard, fast/scalping, slow/swing). However, it doesn't explicitly state when to use this versus other indicator tools like RSI or Bollinger Bands, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate RSI (Relative Strength Index) - a momentum oscillator that measures overbought/oversold conditions. RSI ranges from 0-100. Values above 70 indicate overbought, below 30 indicate oversold. Common period values: 7 (scalping), 14 (day trading), 21 (swing trading).
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| period | Yes | RSI period (2-50). Common: 7 (scalping), 14 (standard), 21 (swing) | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what RSI is and its interpretation, but lacks details on behavioral traits such as computational requirements, rate limits, error handling, or what the output looks like (e.g., single value vs. time series). This leaves gaps for an AI agent to understand how to invoke and interpret results effectively.
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 appropriately sized and front-loaded, starting with the core purpose and key details (RSI definition, ranges, thresholds) before providing usage tips. Every sentence adds value without redundancy, making it efficient and well-structured for quick comprehension.
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 no annotations and no output schema, the description provides good foundational context on RSI and parameter usage, but lacks completeness in behavioral aspects (e.g., output format, error cases) and does not fully compensate for the absence of structured data. It's adequate for basic understanding but has clear gaps for comprehensive tool 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 description coverage is 100%, providing detailed descriptions for all parameters (asset, interval, period, limit). The description adds some semantic context by explaining common period values (7, 14, 21) for different trading styles, which complements the schema. However, it does not add significant meaning beyond what the schema already documents, such as explaining interactions between parameters or additional constraints.
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 calculates the Relative Strength Index (RSI), specifying it's a momentum oscillator that measures overbought/oversold conditions. It distinguishes from siblings like get_indicator_atr or get_indicator_macd by focusing specifically on RSI, making the purpose explicit and differentiated.
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 for usage by explaining RSI ranges (0-100) and thresholds (above 70 for overbought, below 30 for oversold), and suggests common period values for different trading styles (7 for scalping, 14 for day trading, 21 for swing trading). However, it does not explicitly state when to use this tool versus alternatives like other indicators (e.g., MACD or Bollinger Bands) or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate SMA (Simple Moving Average) - a classic trend indicator. Price above SMA suggests uptrend, below suggests downtrend. Slower to react than EMA. Common periods: 20, 50, 100, 200.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| period | Yes | SMA period (5-200). Common: 20, 50, 100, 200 | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes what SMA is and its interpretation in trading, but doesn't disclose behavioral traits like whether this is a read-only operation, what the output format looks like, potential rate limits, or authentication needs. The description adds some context about SMA characteristics but lacks operational details.
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 appropriately sized with four concise sentences that each earn their place: defines SMA, explains interpretation, compares to EMA, and lists common periods. It's front-loaded with the core purpose and wastes no 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 no annotations and no output schema, the description provides good conceptual context about SMA but lacks operational completeness. It doesn't describe what the tool returns (just SMA values? with timestamps?), error conditions, or practical implementation details needed for an agent to use it effectively.
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 the baseline is 3. The description doesn't add meaning beyond what the input schema provides - it mentions common periods (20, 50, 100, 200) which is already in the schema's period parameter description. No additional parameter semantics are provided.
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 calculates SMA (Simple Moving Average), which is a specific verb ('calculate') and resource ('trend indicator'). It distinguishes from siblings by mentioning SMA specifically and contrasting it with EMA, which is a sibling tool (get_indicator_ema).
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 about when SMA is useful ('Price above SMA suggests uptrend, below suggests downtrend') and mentions 'Slower to react than EMA' which implicitly guides usage compared to the EMA sibling. However, it doesn't explicitly state when to use this tool versus other indicator siblings like RSI or MACD.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate Stochastic Oscillator - a momentum indicator comparing closing price to price range. Returns %K and %D lines. Values above 80 indicate overbought, below 20 indicate oversold. %K crossing above %D is bullish signal. Common settings: (14,3) standard, (5,3) fast, (21,7) slow.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset symbol | |
| interval | Yes | Candle interval/timeframe | |
| k_period | Yes | %K period (3-30). Common: 5 (fast), 14 (standard), 21 (slow) | |
| d_period | Yes | %D period (2-10). Common: 3 | |
| limit | Yes | Number of data points to return (10-500). Use 10-20 for quick checks, 50-100 for recent trend, 200+ for historical analysis. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It explains what the indicator measures and how to interpret results, but doesn't mention computational characteristics like whether it requires historical data, potential rate limits, or error conditions. The description adds value about the indicator's purpose but lacks operational transparency.
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 perfectly structured and concise - every sentence earns its place. It starts with the core purpose, explains what it returns, provides interpretation guidelines, and ends with practical configuration advice. No wasted words or redundant information.
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 calculation tool with no annotations and no output schema, the description does well by explaining what the indicator is, what it returns, how to interpret results, and common configurations. However, it doesn't describe the return format or structure, which would be helpful since there's no output schema to reference.
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 the schema already documents all parameters thoroughly. The description adds meaningful context by explaining common settings ('Common settings: (14,3) standard, (5,3) fast, (21,7) slow') which helps the agent choose appropriate values, though it doesn't add syntax details 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 the tool's purpose: 'Calculate Stochastic Oscillator - a momentum indicator comparing closing price to price range. Returns %K and %D lines.' It specifies the verb ('calculate'), resource ('Stochastic Oscillator'), and output ('%K and %D lines'), distinguishing it from sibling indicator tools like RSI or MACD.
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 for when to use this tool by explaining interpretation guidelines ('Values above 80 indicate overbought, below 20 indicate oversold. %K crossing above %D is bullish signal') and common settings. However, it doesn't explicitly state when to choose this over alternative indicators like RSI or MACD from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves current market state for all trading assets (SOL, ETH, BTC). Returns timestamp and market data including: index prices, 24h statistics (change %, high, low, volume), trading fees (base fee %, max price impact %), and for both long/short sides: hourly borrow rates, utilization %, and available liquidity in USD. Note: Short positions use a shared USDC liquidity pool, so short_side metrics (utilization, borrow rate) are identical across all assets. Long positions borrow asset-specific tokens, so long_side metrics vary by asset.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by detailing the returned data structure (timestamp, market data, statistics, fees, borrow rates, utilization, liquidity) and explains key operational nuances like shared USDC pool for short positions versus asset-specific tokens for long positions. However, it does not mention potential rate limits, error conditions, or data freshness guarantees.
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 efficiently structured in two sentences: the first states the purpose and lists returned data, the second explains critical behavioral nuances about liquidity pools. Every sentence adds essential information with zero waste, making it easy to parse and understand quickly.
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 complexity (retrieving multi-asset market data) and lack of output schema, the description provides substantial context about return values, data fields, and operational details. It covers the core functionality well but could be more complete by addressing potential limitations, update frequency, or error handling to fully compensate for the absence of annotations and 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?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on output semantics, explaining what data is returned without redundant parameter details. It adds value by clarifying the structure and meaning of the returned market data beyond what a minimal schema would provide.
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 with a specific verb ('Retrieves') and resource ('current market state for all trading assets'), listing the exact assets (SOL, ETH, BTC). It distinguishes from siblings like get_candles or get_account_portfolio by focusing on comprehensive market-wide data rather than historical charts or account-specific information.
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 implies usage for obtaining real-time market metrics, but does not explicitly state when to use this tool versus alternatives like get_candles for historical data or get_account_portfolio for user-specific holdings. It provides some context about the data scope but lacks explicit guidance on use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submits a transaction to open a new position or increase an existing one. The protocol processes asynchronously (may take a few seconds) - use get_account_portfolio to verify. Returns transaction signature (for logging) and confirmation message.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | The asset to trade | |
| side | Yes | Direction of the trade | |
| collateral_amount | Yes | Amount of USDC to use as collateral (minimum: 10 USD, must be <= wallet balance) | |
| leverage | Yes | Leverage multiplier (added size = collateral * leverage) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it's a transaction submission (implies mutation/write), processes asynchronously with timing ('may take a few seconds'), and returns specific outputs (signature and message). It lacks details on permissions, rate limits, or error handling, but covers core behavior adequately.
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 front-loaded with the core purpose, followed by behavioral details and usage note, all in three concise sentences with zero wasted words. Each sentence adds essential value 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 complexity (transaction submission with 4 required parameters) and no annotations or output schema, the description is largely complete: it explains the action, asynchronous behavior, verification method, and return values. It could improve by mentioning prerequisites (e.g., wallet setup) or error cases, but covers the essentials well for the 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what the schema provides (e.g., no extra context on asset selection or leverage implications), meeting the baseline of 3 for high schema 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 specific action ('Submits a transaction to open a new position or increase an existing one'), identifies the resource (position), and distinguishes from siblings like close_position (which closes) and estimate_open_position (which estimates without submitting).
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 for when to use it (to open/increase positions) and mentions using get_account_portfolio to verify after asynchronous processing. However, it does not explicitly state when NOT to use it (e.g., vs. estimate_open_position for simulation) or detail alternatives beyond verification.
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.
v1.0.0close_positionestimate_open_positionget_account_portfolioget_candlesget_indicator_atrget_indicator_bollinger_bandsget_indicator_emaget_indicator_macdget_indicator_rsiget_indicator_smaget_indicator_stochasticget_market_snapshotopen_positionScored across 13 tools
Most tools have distinct purposes, but there is some overlap between open_position and estimate_open_position, as both relate to opening positions, which could cause confusion. However, their descriptions clarify that one executes trades while the other estimates, aiding disambiguation. The indicator tools (e.g., get_indicator_atr, get_indicator_rsi) are clearly differentiated by the specific technical indicator they calculate.
Tool names follow a highly consistent verb_noun pattern throughout, with clear prefixes like 'get_' for retrieval, 'close_' for actions, and 'estimate_' for calculations. All tools use snake_case uniformly, making them predictable and easy to parse for an agent.
With 13 tools, the count is reasonable for a perps trading server, covering core operations and technical analysis. It might be slightly heavy due to multiple indicator tools, but each serves a distinct purpose, so it remains well-scoped overall.
The toolset provides strong coverage for perps trading, including position management (open, close, portfolio), market data (snapshot, candles), and technical analysis (multiple indicators). A minor gap is the lack of tools for modifying existing positions (e.g., partial close or adjust leverage), but agents can work around this using open_position and close_position.
Non-custodial DeFi tools for AI agents on Solana: swaps, perps, lending, staking, equities.
Non-custodial trading for AI agents: 1,900+ assets — US stocks, treasuries, gold, 250+ perps.
Solana onchain intelligence for AI agents: wallet risk, due-diligence, perps funding, smart money.
Crypto perps data for AI agents: funding rates, open interest, liquidations, order book, CVD.
