> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/reference/mcp-tools.md).

# MCP Tools

Gotts Safe (`@gotts.ai/safe`) exposes Uniswap protocol access as MCP tools. Tools are organized into profiles for selective activation — operators choose which categories to load via the `GOTTS_PROFILE` environment variable.

## Profile System

Profiles use additive inheritance. Each profile includes all tools from its parent profiles, so `lp` automatically includes `trader` tools, which in turn includes `data` tools.

```
data ─────────────────────────── base read-only tools
  ├── trader ──────────────────── + swap execution + streaming
  │     └── lp ────────────────── + liquidity management + batch ops
  ├── vault ───────────────────── + vault tools (24 core + proxy)
  ├── fees ────────────────────── + TokenJar/Firepit tools + streaming
  ├── erc8004 ─────────────────── + identity/reputation tools
  │     └── intelligence ──────── + analysis/order flow/LP intel tools
  └── dashboard ───────────────── + portfolio/P&L/observability
learning ─────────────────────── standalone, composable with any profile
full ─────────────────────────── all of the above + CCA/am-AMM stubs
  └── dev ─────────────────────── + debug tools
```

### Composable Profiles

Set multiple profiles with a comma-separated list:

```bash
GOTTS_PROFILE=trader,vault     # Trading + vault tools
GOTTS_PROFILE=data,learning    # Read-only data + self-improvement
```

### Write vs Read Profiles

Write profiles (`trader`, `lp`, `vault`, `fees`, `full`, `dev`) require wallet configuration. Read-only profiles (`data`, `erc8004`, `intelligence`, `dashboard`) work without a wallet.

## Tool Categories

| Category                 | Profile        | Count  | Status      |
| ------------------------ | -------------- | ------ | ----------- |
| Data & Analytics         | `data`         | 26     | Implemented |
| Token Directory          | `data`         | (incl) | Implemented |
| Portfolio & P\&L         | `data`         | (incl) | Implemented |
| Utility                  | `data`         | 2      | Implemented |
| Trading                  | `trader`       | 9      | Implemented |
| Trader Streaming         | `trader`       | 2      | Implemented |
| Liquidity                | `lp`           | 10     | Implemented |
| LP Streaming & Batch     | `lp`           | 4      | Implemented |
| ERC-8004 Identity        | `erc8004`      | 8      | Implemented |
| Order Flow Intelligence  | `intelligence` | 3      | Implemented |
| Analytics & Intelligence | `intelligence` | 4      | Implemented |
| Advanced Analytics       | `intelligence` | 3      | Implemented |
| LP Intelligence          | `intelligence` | 3      | Implemented |
| Protocol Fees            | `fees`         | 6      | Implemented |
| Memory & Knowledge       | `learning`     | 10     | Implemented |
| Self-Improvement         | `dashboard`    | 6      | Implemented |
| CCA Stubs                | `full`         | 6      | Preview     |
| am-AMM Stubs             | `full`         | 3      | Preview     |
| Vault (Factory)          | `vault`        | —      | Planned     |
| Agent Proxy              | `vault`        | —      | Planned     |

## Data Tools (28 tools)

Profile: `data`

| Tool                            | Description                                  |
| ------------------------------- | -------------------------------------------- |
| `get_token_price`               | Current USD price of a token                 |
| `get_pool_info`                 | Pool details with live on-chain state        |
| `get_pools_by_token_pair`       | Find pools for a token pair                  |
| `get_pools_by_token`            | Find pools containing a token                |
| `get_new_pools`                 | Recently created pools                       |
| `get_position`                  | LP position details by NFT ID                |
| `get_positions_by_owner`        | All positions for a wallet                   |
| `get_tick_data`                 | Initialized tick data for liquidity analysis |
| `get_pool_health_score`         | Composite health score (0-100)               |
| `get_token_price_history`       | Historical OHLCV candles                     |
| `get_trade_history`             | Recent swaps for a pool                      |
| `get_pool_volume_history`       | Historical volume/TVL/fees                   |
| `get_token_list`                | Well-known tokens with prices                |
| `search_tokens`                 | Fuzzy token search                           |
| `get_token_metadata`            | ERC-20 metadata + proxy detection            |
| `get_account_balance`           | Wallet token balances with USD values        |
| `get_wallet_balance_history`    | Historical balance from Transfer events      |
| `get_portfolio_snapshot`        | Point-in-time portfolio snapshot             |
| `get_realized_pnl`              | Realized P\&L from Transfer events           |
| `get_unrealized_pnl`            | Unrealized P\&L for current holdings         |
| `get_fee_earnings_history`      | LP fee earnings history                      |
| `get_transaction_cost_analysis` | Gas cost analysis                            |
| `get_performance_metrics`       | Sharpe, Sortino, max drawdown                |
| `compare_portfolio_periods`     | Portfolio change between blocks              |
| `get_pnl_report`                | Unified P\&L report                          |
| `stress_test_portfolio`         | Scenario stress testing + VaR                |
| `generate_uniswap_link`         | Build app.uniswap.org deep links             |
| `unsubscribe`                   | Cancel any active subscription               |

## Trading Tools (11 tools)

Profile: `trader` (includes `data`)

| Tool                        | Description                         |
| --------------------------- | ----------------------------------- |
| `get_quote`                 | Get swap quote from Uniswap API     |
| `execute_swap`              | Execute a token swap                |
| `submit_uniswapx_order`     | Submit UniswapX Dutch auction order |
| `get_uniswapx_order_status` | Check UniswapX order status         |
| `submit_cross_chain_intent` | Submit ERC-7683 cross-chain intent  |
| `check_allowance`           | Check ERC-20 token allowance        |
| `approve_token`             | Approve token spending              |
| `sign_permit2`              | Sign Permit2 typed data             |
| `batch_permit2`             | Batch Permit2 approvals             |
| `subscribe_price_feed`      | Real-time price feed subscription   |
| `subscribe_trades`          | Real-time swap event subscription   |

## Liquidity Tools (15 tools)

Profile: `lp` (includes `trader`)

| Tool                        | Description                        |
| --------------------------- | ---------------------------------- |
| `add_liquidity`             | Open new LP position               |
| `remove_liquidity`          | Close LP position                  |
| `collect_fees`              | Collect accrued fees               |
| `increase_liquidity`        | Add to existing position           |
| `compound_fees`             | Auto-compound fees into position   |
| `rebalance_position`        | Rebalance position range           |
| `submit_twamm_order`        | Submit TWAMM order                 |
| `get_twamm_order_status`    | Check TWAMM order status           |
| `migrate_position`          | Migrate position (V3->V4)          |
| `claim_lp_rewards`          | Claim LP reward incentives         |
| `batch_lp_operations`       | Atomic batch LP operations         |
| `subscribe_pool_events`     | Real-time Mint/Burn/Collect events |
| `subscribe_pool_state`      | Real-time pool state updates       |
| `subscribe_position_alerts` | IL/range alerts for positions      |

## ERC-8004 Identity Tools (8 tools)

Profile: `erc8004` (includes `data`)

| Tool                    | Description                       |
| ----------------------- | --------------------------------- |
| `register_agent`        | Register on-chain agent identity  |
| `get_agent_profile`     | Get agent profile + IPFS metadata |
| `discover_agents`       | Search agents by capability       |
| `query_reputation`      | Query agent reputation score      |
| `update_agent_metadata` | Update agent metadata URI         |
| `get_agent_credentials` | Get agent verifiable credentials  |
| `verify_agent_identity` | Composite identity verification   |
| `get_agent_tier`        | Get tier + next tier requirements |

## Intelligence Tools (14 tools)

Profile: `intelligence` (includes `data` + `erc8004`)

| Tool                          | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| `compute_vpin`                | Volume-synchronized probability of informed trading |
| `compute_lvr`                 | Loss-versus-rebalancing estimation                  |
| `get_order_flow_metrics`      | Composite order flow analysis                       |
| `discover_token`              | Multi-source token discovery + risk scoring         |
| `assess_mev_risk`             | MEV risk assessment for trades                      |
| `compare_venues`              | Compare V2/V3/V4/UniswapX quotes                    |
| `calculate_il`                | Exact V3 impermanent loss calculation               |
| `get_agent_revenue`           | Aggregate agent revenue streams                     |
| `simulate_price_impact`       | Simulated price impact via eth\_call                |
| `calculate_fee_switch_impact` | Fee switch impact modeling                          |
| `optimize_lp_range`           | Monte Carlo LP range optimization                   |
| `recommend_fee_tier`          | Optimal fee tier recommendation                     |
| `backtest_lp_strategy`        | Historical LP strategy backtesting                  |
| `detect_account_type`         | Classify EOA/ERC-4337/ERC-7702/Safe                 |

## Protocol Fee Tools (6 tools)

Profile: `fees` (includes `data`)

| Tool                        | Description                        |
| --------------------------- | ---------------------------------- |
| `get_tokenjar_balances`     | TokenJar accumulated fee balances  |
| `get_firepit_state`         | Firepit burn state + profitability |
| `get_burn_history`          | Historical burn events             |
| `execute_burn`              | Execute UNI burn via Firepit       |
| `get_fee_accumulation_rate` | Fee accumulation rate over time    |
| `subscribe_tokenjar`        | Real-time TokenJar transfer events |

## Memory & Knowledge Tools (10 tools)

Profile: `learning` (standalone, composable)

| Tool                         | Description                             |
| ---------------------------- | --------------------------------------- |
| `store_strategy`             | Store trading strategy for retrieval    |
| `classify_regime`            | Classify current market regime          |
| `retrieve_strategies`        | Retrieve strategies matching conditions |
| `assess_historical_exposure` | Assess historical risk exposure         |
| `store_episode`              | Store experience episode                |
| `search_memory`              | Semantic memory search                  |
| `get_insights`               | Get learned insights                    |
| `manage_insight`             | Create/update/archive insights          |
| `consolidate_memories`       | Consolidate memory entries              |
| `get_memory_stats`           | Memory system statistics                |

## Self-Improvement Tools (6 tools)

Profile: `dashboard`

| Tool                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `record_execution`              | Record tool execution for analysis |
| `record_outcome`                | Record execution outcome           |
| `compare_predicted_vs_actual`   | Compare predictions to actuals     |
| `get_failure_patterns`          | Analyze failure patterns           |
| `generate_reinforcement_signal` | Generate learning signal           |
| `tune_parameters`               | Auto-tune strategy parameters      |

## CCA / am-AMM Stubs (9 tools)

Profile: `full` only. These tools return preview status — CCA and am-AMM are not yet live on mainnet.

| Tool                           | Description              | Status  |
| ------------------------------ | ------------------------ | ------- |
| `get_cca_state`                | CCA auction state        | Preview |
| `submit_cca_bid`               | Submit CCA bid           | Preview |
| `exit_cca_bid`                 | Exit CCA bid             | Preview |
| `claim_cca_tokens`             | Claim CCA tokens         | Preview |
| `launch_token`                 | Launch token via CCA     | Preview |
| `generate_cca_supply_schedule` | Generate supply schedule | Preview |
| `get_amamm_state`              | am-AMM pool state        | Preview |
| `submit_amamm_bid`             | Submit am-AMM bid        | Preview |
| `get_amamm_bid_status`         | Check am-AMM bid status  | Preview |

## Library Exports

The `@gotts.ai/safe` package also exports its infrastructure for use by other packages:

```typescript
import {
  // Configuration
  loadConfig,
  getConfig,

  // Error types
  GottsError,
  SafetyError,
  ValidationError,
  DataError,
  ErrorCodes,

  // Cache
  Cache,
  CacheTTL,
  cacheKey,

  // Providers
  getClient,
  getSupportedChains,
  querySubgraph,

  // Constants
  CHAIN_CONFIGS,
  SUPPORTED_CHAIN_IDS,
  PERMIT2_ADDRESS,
  ERC20_ABI,

  // Types
  type ChainId,
  type ToolProfile,
  type ToolResult,
} from "@gotts.ai/safe";
```