Q AI — Tools Reference — YoorQuezt Docs

Q AI provides 40+ tools that the agentic loop can invoke in response to natural language queries. Tools are organized into 7 categories and are filtered by the user's RBAC role.

Tool Flags

Mutating -- the tool modifies engine state (submits bundles, cancels, etc.). Marked with a checkmark below.
Confirm -- the tool requires explicit user confirmation before execution. All mutating tools require confirmation.

Engine Tools (5)

Tool	Description	Mutating	Confirm
`engine_health`	Check engine health, uptime, and version
`engine_metrics`	Retrieve Prometheus metrics snapshot
`engine_config`	View current engine configuration
`engine_chains`	List connected chains and their status
`engine_status`	Comprehensive status: chains, relays, bundles, profit

Bundle Tools (10)

Tool	Description	Mutating	Confirm
`bundle_submit`	Submit a bundle to the MEV engine	yes	yes
`bundle_status`	Check status of a submitted bundle by hash
`bundle_simulate`	Simulate a bundle without submitting
`bundle_cancel`	Cancel a pending bundle	yes	yes
`bundle_list`	List recent bundles with optional filters
`bundle_profit`	Profit breakdown for a specific bundle
`bundle_history`	Historical bundle data with date range
`bundle_gas`	Estimate gas for a bundle
`bundle_validate`	Validate bundle structure and parameters
`bundle_decode`	Decode bundle transactions (ABI decoding)

Builder Tools (6)

Tool	Description	Mutating	Confirm
`builder_blocks`	List recent blocks with MEV data
`builder_block`	Get detailed block info by number
`builder_pending`	View current pending block template
`builder_stats`	Builder performance statistics
`builder_relays`	Connected relay status and latency
`builder_bids`	Recent builder bids and outcomes

Validator Tools (6)

Tool	Description	Mutating	Confirm
`validator_auctions`	List recent and active auctions
`validator_auction`	Get specific auction details by ID
`validator_bids`	List bids for a specific auction
`validator_settlements`	Settlement transaction history
`validator_payouts`	Payout history for settled auctions
`validator_stats`	Validator-side statistics

Operator Tools (8)

Tool	Description	Mutating	Confirm
`ops_health`	System-wide health overview
`ops_relays`	Relay connection management and status
`ops_mempool`	Inspect current mempool state
`ops_peers`	Connected P2P mesh peers
`ops_config`	View and update runtime configuration	yes	yes
`ops_logs`	Retrieve recent log entries
`ops_alerts`	View active alerts and notifications
`ops_diagnostics`	Run diagnostic checks on components

Analyst Tools (7)

Tool	Description	Mutating	Confirm
`analyst_profit`	Profit analytics with time range and grouping
`analyst_strategies`	Strategy performance breakdown
`analyst_chains`	Per-chain MEV analytics
`analyst_trends`	MEV trend analysis over time
`analyst_competition`	Competitive analysis (win rates, market share)
`analyst_gas`	Gas market analysis and predictions
`analyst_forensics`	MEV forensic reports for wallets or protocols

MCP Ops Tools (16)

These tools are served by the MCP server and are read-only. See MCP Server for detailed documentation.

Tool	Description	Mutating	Confirm
`platform_health_summary`	Overall platform health summary
`get_active_ride`	Current active auction details
`get_ride`	Specific auction by ID
`get_order`	Bundle details by hash
`list_orders`	List recent bundles
`list_stale_orders`	Bundles stuck in pending state
`order_funnel_stats`	Bundle lifecycle funnel metrics
`get_booking`	Block details
`get_assignment`	Relay assignment for a block
`list_assignments`	All relay assignments
`get_wallet`	Wallet balance and history
`get_payment_intent`	Payment intent status
`list_payment_methods`	Available payment methods
`get_surge_pricing`	Gas surge pricing data
`get_available_slots`	Available builder slots
`explain_error`	Human-readable error explanations

Natural Language to Tool Mapping

Q AI maps natural language queries to tools automatically. Here are examples of how queries resolve:

User Query	Tools Invoked
"Is the engine healthy?"	`engine_health`
"Show me profit from the last 24 hours"	`analyst_profit`
"Profit by chain this week"	`analyst_profit`, `analyst_chains`
"What's in the mempool?"	`ops_mempool`
"Submit this bundle: [0xabc, 0xdef]"	`bundle_validate` then `bundle_submit` (with confirmation)
"Simulate these transactions"	`bundle_simulate`
"How are the relays performing?"	`builder_relays`, `ops_relays`
"What MEV was in block 19482300?"	`builder_block`
"Show me stale bundles"	`list_stale_orders`
"Run diagnostics"	`ops_diagnostics`
"Forensic report for wallet 0x1234..."	`analyst_forensics`
"Compare strategies this month"	`analyst_strategies`, `analyst_trends`
"What's the current auction?"	`get_active_ride`
"Cancel bundle 0xbundle_hash"	`bundle_cancel` (with confirmation)
"Gas market analysis"	`analyst_gas`, `get_surge_pricing`

Multi-Tool Queries

Q AI can invoke multiple tools in a single query. The agentic loop iterates until all necessary data is gathered:

User: "Compare Ethereum and BSC profit this week, and show relay performance"

Tool calls:
  1. analyst_profit(chain="ethereum", range="7d")
  2. analyst_profit(chain="bsc", range="7d")
  3. builder_relays()
  4. ops_relays()

Response: "Here's your weekly comparison:
  Ethereum: 4.21 ETH profit (89 bundles)
  BSC: 1.87 BNB profit (203 bundles)
  ..."

Custom Tool Parameters

Most tools accept optional parameters for filtering and formatting:

// analyst_profit with parameters
{
  "tool": "analyst_profit",
  "arguments": {
    "chain": "ethereum",
    "range": "7d",
    "group_by": "strategy",
    "format": "table"
  }
}

// bundle_list with filters
{
  "tool": "bundle_list",
  "arguments": {
    "status": "landed",
    "chain": "ethereum",
    "limit": 20,
    "since": "2026-03-14T00:00:00Z"
  }
}