ensotrade

Test Formula

test_formula

Invent a formula over EnsoTrade's data, and get back whether it actually predicts forward returns — validated on a holdout split, not just fit to the whole window. formula is a math expression combining any of the fields listed in fetch_series' docstring (for the same timeframe) with +, -, *, /, **, %, unary +/-, and abs/min/max/ sqrt/log/log1p/exp/sign/clip/mean/std, e.g. "ofi1 * vpin - dofi / 2" or "sign(qi) * sqrt(abs(obi))". No other Python is executed — this runs through a restricted, default-deny expression evaluator, not eval().

timeframe="scalp" (default, WDE order-flow, second-scale): horizon is which forward return to correlate against — ret_1s_bp, ret_5s_bp, ret_30s_bp, or ret_60s_bp. hours max 720 (30 days).

timeframe = "15m"/"1h"/"4h"/"1d" for day/swing strategies (real OKX candles, always available): use horizon_bars instead of horizon — the forward % return N candles ahead (e.g. horizon_bars=4 on timeframe="1h" = predicting the move 4 hours out). hours max ~1500 bars worth; a small hours still fetches at least 150 bars (the minimum needed for a meaningful 70/30 split) rather than failing outright, so the actual window tested can be wider than requested for a small hours value.

Either mode needs enough rows that a 70/30 split leaves >=150 total. Returns train (first 70% chronologically) and holdout (untouched final 30%) Spearman/Pearson correlations plus a verdict: 'validated' only if holdout |spearman| >= 0.15 AND same-signed as train — this guards against keeping a formula that only looked good by chance on one slice of data.

ALSO returns, computed on the holdout portion only:

net: risk-adjusted performance AFTER trading costs — sharpe, sortino, max_drawdown_pct, calmar, ann_return_pct, ann_volatility_pct, win_rate_pct, profit_factor. Sharpe is annualized and corrected for overlapping horizons (a horizon spanning N bars sampled every bar is subsampled to non-overlapping periods first, which removes the ~sqrt(N) inflation naive Sharpe would show).
gross: the same metrics before costs, so the cost drag is visible.
costs: fee/slippage assumptions, position_changes (turnover), total_cost_pct. Costs are charged on position CHANGES only, not per bar — holding one side is cheap, flipping every bar is not.
cost_verdict: survives_costs / marginal_after_costs / killed_by_costs / unknown. IMPORTANT: verdict is a correlation test and says nothing about profitability; a formula can be 'validated' and still be killed_by_costs. Check both.
walk_forward: the same formula re-scored on 5 consecutive time blocks, with consistency_pct (share of blocks agreeing on direction) and a stable flag. An edge that passes one holdout but flips sign between blocks is usually noise.

fee_bp/slippage_bp are per side, defaulting to 5bp taker + 2bp slippage; raise them for illiquid coins or a worse fee tier. Iterate: call this repeatedly with different formulas, keep what validates AND survives costs, discard what doesn't. Requires an EnsoTrade Pro API key.

Input Schema

TableJSON Schema

Name	Required	Default
`hours`	No
`fee_bp`	No
`symbol`	Yes
`formula`	Yes
`horizon`	No	ret_30s_bp
`timeframe`	No	scalp
`slippage_bp`	No
`horizon_bars`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations provided, the description carries full responsibility, and it does an excellent job. It discloses the restricted evaluator (no eval, default-deny), the validation methodology (70/30 chronological split, same-sign requirement), how costs are charged (only on position changes), the meaning of verdict vs. cost_verdict, and walk-forward stability checks. No behavioral surprises are left unmentioned.

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 description is long but well-structured with clear sections. Each paragraph adds necessary context; there is no fluff. It earns a 4 rather than 5 only because the length, while justified, could be slightly tightened for faster parsing by an agent.

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?

For a complex tool with 8 parameters and a rich output schema, this description is remarkably complete. It covers formula syntax, data availability, timeframes, cost modeling, return metrics, verdict logic, and practical iteration advice. An agent has everything needed to invoke the tool correctly and interpret its results.

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

Parameters5/5

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

The input schema has 0% description coverage, yet the tool description explains every parameter: symbol, formula (with syntax and allowed operators), timeframe (modes), horizon vs. horizon_bars, hours limits, fee_bp and slippage_bp defaults and guidance. It even warns about minimum data requirements. This fully compensates for the sparse schema.

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 clearly states a specific verb and resource: 'Invent a formula over EnsoTrade's data, and get back whether it actually predicts forward returns' — a testing/validation tool for formulas. It distinguishes itself from sibling tools by describing a unique workflow of hypothesis testing against a holdout split, which is not present in other tool names.

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?

The description explicitly instructs when to use this tool: 'Iterate: call this repeatedly with different formulas, keep what validates AND survives costs, discard what doesn't.' It also explains mode-specific usage (scalp vs. day/swing) and parameter choices. This is more than sufficient for an agent to select it over siblings.

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

All ensotrade tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.8/5.0

Disambiguation4/5

Most tools target distinct analytics functions (order flow, execution cost, strategy testing, market scans). A few pairs overlap—mass_map/mass_scan, market_rotation/top_movers, and market_snapshot/perp_dashboard—but descriptions clarify differences. No tools are truly indistinguishable.

Naming Consistency3/5

Naming style is mixed: some tools use verb+noun (explain_move, fetch_series, get_funding) while others use descriptive noun phrases (carry_pressure, currency_leg, exit_capacity). The names are readable and meaningful, but the pattern is not uniform. It is not chaotic, but lacks a single consistent convention.

Tool Count4/5

22 tools is on the heavier side but reasonable for a comprehensive crypto analytics suite covering market data, execution analysis, risk, and strategy testing. Each tool serves a distinct purpose and contributes to the overall scope. It is not excessive enough to feel bloated.

Completeness5/5

The tool set covers the full analytics lifecycle: market overview, order-flow explanation, execution routing and cost, position limits, options, and strategy backtesting. There are no obvious dead ends; users can research, test, and validate strategies. The coverage is thorough for the stated trading-analytics domain.

Resources

Need Help?