> 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/gotts-vaults/vault/08-mcp-tools.md).

# MCP Tools

> **Part of**: [Vault PRD](/docs/gotts-vaults/vault.md) | **Last Updated**: 2026-02-13

***

## MCP Tool Inventory (Normative)

> **This chapter is the single source of truth** for vault tool names, counts, scope, and parameter contracts. All other documents (README, IMPLEMENTATION-STATE, architecture docs) MUST reference these counts rather than maintaining independent tallies.

| Scope                                    |  Count | Status                       | Owner                      |
| ---------------------------------------- | -----: | ---------------------------- | -------------------------- |
| Core v1 vault tools                      |     24 | 0 shipped, 24 spec           | `packages/vault`           |
| am-AMM strategy auction tools            |      5 | Spec only (Phase 3)          | `packages/vault`           |
| Optional proxy tools (standalone module) |      6 | Spec only                    | `packages/agent-proxy`     |
| Deferred tools (4 CCA + 4 growth)        |      8 | Spec only (post-v1)          | `packages/vault` expansion |
| Strategy marketplace tools               |      6 | Spec only (learning economy) | `packages/vault`           |
| **Roadmap total**                        | **49** |                              |                            |

***

## Contract Conventions

### Parameter conventions

* `agentId`: ERC-8004 agent ID as string (e.g. `"42"`)
* `vaultAddress`: EVM address string
* `assets`: smallest-unit token amount string (e.g. `"1000000"` for 1 USDC)
* `shares`: smallest-unit share amount string
* `chain`: chain name or chain ID string

### Return conventions

* Read tools return deterministic JSON data from chain state and indexed sources.
* Write tools return at minimum:
  * `status`: `"submitted" | "confirmed" | "failed"`
  * `txHash`: transaction hash when applicable
  * `summary`: short human-readable action summary

***

## Error Taxonomy

All vault MCP tools return structured errors with machine-readable error codes. Each error maps to the safety layer that generates it (see [shared/safety-layers.md](/docs/prd-shared/safety-layers.md)).

| Error Code                | HTTP-like | Safety Layer               | Description                                                            | Affected Tools                                       |
| ------------------------- | --------- | -------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------- |
| `AGENT_NOT_REGISTERED`    | 403       | Layer 0 (Identity)         | Agent ID is not a valid ERC-8004 identity or credential is frozen      | All write tools                                      |
| `DEPOSIT_EXCEEDS_TIER`    | 403       | Layer 0 (Identity)         | Deposit amount exceeds the agent's reputation tier cap                 | `vault_deposit`, `vault_simulate_deposit`            |
| `VAULT_PAUSED`            | 503       | Layer 10 (Circuit Breaker) | Vault is paused due to circuit breaker trigger or creator pause        | All write tools                                      |
| `CIRCUIT_BREAKER_ACTIVE`  | 503       | Layer 10 (Circuit Breaker) | Drawdown or withdrawal velocity breaker is active; operations dampened | `vault_withdraw`, `vault_rebalance`                  |
| `INSUFFICIENT_GAS`        | 402       | Layer 6 (Simulation)       | Pre-flight simulation estimates gas exceeds agent balance              | All write tools                                      |
| `ORACLE_STALE`            | 503       | Layer 10 (NAV)             | Required oracle feed is stale; NAV pricing disabled                    | `vault_deposit`, `vault_withdraw`, `vault_rebalance` |
| `PROXY_DELAY_NOT_ELAPSED` | 425       | Layer 4 (Proxy)            | Time-delayed proxy announcement has not reached execution window       | `proxy_execute`                                      |
| `PROXY_CANCELLED`         | 410       | Layer 5 (Monitoring)       | Pending proxy announcement was cancelled by cancel authority           | `proxy_execute`                                      |
| `SPENDING_LIMIT_EXCEEDED` | 403       | Layer 3 (Policy)           | Operation exceeds per-tx, per-session, or per-day spending limit       | All write tools                                      |
| `SIMULATION_FAILED`       | 422       | Layer 6 (Simulation)       | `eth_call` simulation reverted; transaction would fail on-chain        | All write tools                                      |
| `SLIPPAGE_EXCEEDED`       | 422       | Layer 7 (Guards)           | Estimated slippage exceeds configured maximum                          | `vault_rebalance`                                    |
| `VAULT_NOT_FOUND`         | 404       | --                         | Address is not a factory-registered vault                              | All tools                                            |
| `INVALID_CHAIN`           | 400       | --                         | Specified chain is not supported                                       | All tools                                            |
| `INSUFFICIENT_SHARES`     | 422       | --                         | Agent does not hold enough shares for the withdrawal                   | `vault_withdraw`                                     |

**Error response format:**

```json
{
  "error": {
    "code": "DEPOSIT_EXCEEDS_TIER",
    "message": "Deposit of 100,000 USDC exceeds Verified tier cap of 50,000 USDC for agent 42",
    "safetyLayer": 0,
    "suggestedAction": "Reduce deposit amount to 50,000 USDC or increase reputation to Trusted tier (100+ score)"
  }
}
```

***

## Design Rationale

### Intent-Based Tool Grouping

The 24 core tools follow **intent-based grouping** rather than 1:1 contract function mapping. This avoids the "naive API-to-MCP conversion" anti-pattern identified by Thoughtworks (Technology Radar "Hold" category, 2025) where creating one MCP tool per contract function causes context overflow in LLMs and makes the tool surface unmanageable.

Each write tool composes all necessary on-chain steps into a single atomic operation. For example, `vault_deposit` internally:

1. Checks ERC-20 allowance for the vault contract
2. Approves via Permit2 if needed (or standard approve as fallback)
3. Executes the deposit call
4. Returns a unified result with shares received

**Principle**: Multi-step on-chain operations MUST be composed into a single MCP tool. Never expose `approve` and `deposit` as separate tools requiring LLM orchestration. The LLM expresses intent ("deposit 1000 USDC into vault"); the tool handles mechanics.

### Write Confirmation via MCP Elicitation

All write tools that exceed a configurable value threshold trigger **MCP Elicitation** (MCP spec draft, June 2025) to request human confirmation before signing. Elicitation uses Form Mode to present structured confirmation data via JSON Schema.

**When Elicitation triggers**:

| Operation Mode                        | Threshold                                    | Behavior                                                               |
| ------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| Human-supervised agent                | All writes                                   | Elicitation form with operation summary, gas estimate, slippage impact |
| Agent-autonomous (session key scoped) | > `elicitationThresholdUsd` (default $1,000) | Elicitation for high-value ops; within-session-key ops skip            |
| Fully autonomous (no human)           | Never                                        | All operations execute within session key bounds; no Elicitation       |

**Elicitation form schema** (write tools):

```json
{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "description": "Human-readable operation summary"
    },
    "valueUsd": {
      "type": "number",
      "description": "Estimated USD value of the operation"
    },
    "gasEstimate": { "type": "string", "description": "Estimated gas cost" },
    "slippageImpact": {
      "type": "string",
      "description": "Expected slippage (for swaps/rebalances)"
    },
    "confirm": { "type": "boolean", "description": "Confirm execution" }
  },
  "required": ["confirm"]
}
```

Elicitation complements (not replaces) the time-delayed proxy (Layer 4 in safety architecture). Human-supervised agents get both: Elicitation for immediate confirmation, and proxy delay for high-risk operations. The two mechanisms serve different threat models: Elicitation prevents LLM misinterpretation of user intent; proxy delay prevents compromised agent keys from executing silently.

### Memory-Augmented Vault Operations (DeFi Brain)

When `TOOL_PROFILE=vault,learning` (both profiles active), vault tools gain memory augmentation via the DeFi Brain system. The memory layer retrieves relevant episodic memories and semantic insights before vault operations and stores reflections after execution.

**Key vault memory behaviors**:

* **`vault_rebalance`**: Before rebalancing, retrieves past rebalance episodes for this vault (timing, gas costs, slippage, VPIN at time of rebalance). Memory surfaces VPIN-based timing warnings (e.g., "Last 3 rebalances during high VPIN (>0.7) periods incurred 2-3x higher slippage"). After execution, stores episode with detailed reflection on rebalance outcome. Minimum insight confidence for rebalance memory: 0.7 (higher than default 0.5 — see [10-safety.md](/docs/gotts-vaults/vault/10-safety.md) § Vault Memory Safety).
* **`vault_deposit`**: Tracks deposit timing, NAV at entry, reputation tier at deposit time, and gas costs. Builds episodic history for deposit-timing insights (e.g., "Deposits after fee collection events get better NAV entry").
* **`vault_emergency_exit`**: High-importance memory (180+ day stability). Stores detailed reflection on exit conditions: NAV deviation, circuit breaker state, oracle status, loss magnitude. Minimum insight confidence: 0.9. Emergency memories are never pruned by the decay system — they serve as permanent safety knowledge.

Memory adjustments in vault context are further bounded by **PolicyCage** (D-053) — on-chain constraints cannot be exceeded regardless of memory suggestions. Memory may recommend tighter slippage or suggest timing adjustments, but cannot override approved asset lists, max position sizes, rebalance frequency limits, or max drawdown tolerance.

***

## Core v1 Vault Tools (24)

| Category            | Tool                                | Core Parameters                                                                                        |
| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Factory             | `create_vault`                      | `creatorAgentId`, `name`, `symbol`, `baseAsset`, `config`, `chain`                                     |
| Factory             | `list_vaults`                       | `chain`, optional `baseAsset`, `creatorAgentId`, `sortBy`, `limit`, `offset`                           |
| Factory             | `get_vault_config`                  | `vaultAddress`, `chain`                                                                                |
| Deposit             | `vault_deposit`                     | `vaultAddress`, `agentId`, `assets`, `chain`                                                           |
| Deposit             | `vault_withdraw`                    | `vaultAddress`, `agentId`, `shares`, `chain`                                                           |
| Deposit             | `vault_simulate_deposit`            | `vaultAddress`, `agentId`, `assets`, `chain`                                                           |
| Strategy            | `vault_rebalance`                   | `vaultAddress`, `agentId`, optional `strategy`, `dryRun`, `chain`                                      |
| Strategy            | `vault_collect_fees`                | `vaultAddress`, `agentId`, optional `positionIds`, `chain`                                             |
| Strategy            | `vault_migrate_to_v4`               | `vaultAddress`, `positionIds`, `chain`                                                                 |
| Strategy            | `vault_claim_rewards`               | `vaultAddress`, `chain`, `tokens`                                                                      |
| Strategy            | `vault_emergency_exit`              | `vaultAddress`, `targetStable`, `chain`                                                                |
| Read                | `vault_get_state`                   | `vaultAddress`, `chain`                                                                                |
| Read                | `vault_get_strategy`                | `vaultAddress`, `chain`                                                                                |
| Read                | `vault_get_positions`               | `vaultAddress`, `chain`                                                                                |
| Read                | `vault_get_agent_shares`            | `vaultAddress`, `agentId`, `chain`                                                                     |
| Read                | `vault_get_performance`             | `vaultAddress`, optional `period`, `chain`                                                             |
| Read                | `vault_get_risk_metrics`            | `vaultAddress`, `chain`                                                                                |
| Identity/Reputation | `vault_register_agent`              | `vaultAddress`, `agentId`, `chain`                                                                     |
| Identity/Reputation | `vault_get_agent_reputation`        | `agentId`, optional `chain`                                                                            |
| Identity/Reputation | `vault_get_tier_limits`             | `agentId`, `vaultAddress`, optional `chain`                                                            |
| Identity/Reputation | `vault_enroll_reputation`           | `agentId`, `vaultAddress`, optional `chain`                                                            |
| Identity/Reputation | `vault_get_milestones`              | `agentId`, optional `vaultAddress`, optional `chain`                                                   |
| Identity/Reputation | `vault_claim_milestone`             | `agentId`, `milestoneId`, optional `vaultAddress`, optional `chain`                                    |
| Market              | `get_vault_rankings`                | optional `chain`, `baseAsset`, `metric`, `limit`, `offset`                                             |
| Feedback/Discovery  | `vault_submit_yield_feedback`       | `agentId`, `yieldBps`, `tag2` (`week`/`month`/`year`), optional `feedbackURI`, `feedbackHash`, `chain` |
| Feedback/Discovery  | `vault_submit_qualitative_feedback` | `fromAgentId`, `toAgentId`, `score` (0-100), `tag1`, `tag2`, optional `chain`                          |
| Feedback/Discovery  | `vault_get_yield_leaderboard`       | optional `chain`, `asset`, `tag2`, `minFeedbackCount`, `minTier`, `orderBy`, `limit`                   |
| Feedback/Discovery  | `search_yield_opportunities`        | optional `chain`, `asset`, `minApy`, `maxRisk`, `minReputationScore`, `minFeedbackCount`, `limit`      |

**`vault_submit_yield_feedback`** (D-082, D-087): Submit automated per-epoch yield feedback for a vault manager to the ERC-8004 Reputation Registry. Uses `tradingYield` as `tag1`. Yield in basis points (signed -- supports negative yields). Optional `feedbackURI` points to IPFS JSON with Sharpe ratio, drawdown, and IL metrics. `feedbackHash` = keccak256(feedbackURIContents) for tamper evidence. Requires Basic+ tier.

**`vault_submit_qualitative_feedback`** (D-082): Submit qualitative feedback from an investor to a vault manager. Score 0-100 with tag categories (`starred`/`overall`, `successRate`/`deposits`, `responseTime`/`a2a`). Requires Basic+ tier.

**`vault_get_yield_leaderboard`** (D-087): Query the yield leaderboard -- ranked vault managers by yield performance. Filterable by chain, asset, time period, minimum feedback count, and reputation tier. Returns agent ID, name, average yield, Sharpe ratio, max drawdown, TVL, reputation tier, and vault address. Backed by subgraph-indexed `NewFeedback` events filtered by `tradingYield` tag.

**`search_yield_opportunities`** (D-082, D-084): Yield service discovery tool combining ERC-8004 Identity Registry metadata, Reputation Registry feedback, and Agent0 SDK search. Returns ranked yield opportunities with agent identity, vault address, APY metrics, risk metrics, fee structure, reputation tier, and MCP/A2A endpoints. Aggregates internal AgenticVaults data with external benchmarks (DefiLlama, Superform).

**`vault_rebalance`**: Uses Uniswap Trading API when `GOTTS_UNISWAP_API_KEY` is available for swap execution (`/quote` → `/swap`) and LP adjustments (`/lp/decrease` → `/lp/create`). Falls back to direct SDK calls when no API key. Optional `dryRun` parameter returns planned trades without executing.

**`vault_collect_fees`**: Uses `POST /lp/claim` for each position when API key available.

**`vault_migrate_to_v4`**: Migrate vault V3 positions to V4 via `POST /lp/migrate`. Parameters: `vaultAddress`, `positionIds` (array of V3 NFT token IDs), `chain`. Only available when `GOTTS_UNISWAP_API_KEY` is configured (no SDK fallback for migration). Returns new V4 position IDs and migration tx hashes.

**`vault_claim_rewards`**: Claim LP incentive rewards via `POST /lp/claim_rewards`. Parameters: `vaultAddress`, `chain`, `tokens` (reward token addresses array), optional `distributor` (default: "MERKL"). Returns claimed amounts per token and tx hash.

**`vault_emergency_exit`**: Emergency full withdrawal: decrease all positions 100%, claim fees, swap all to target stable. Parameters: `vaultAddress`, `targetStable` (stable token address, e.g., USDC), `chain`. Uses API for all operations when available. Returns total assets recovered and tx hashes.

***

## Optional Proxy Tools (6)

These belong to the standalone `packages/agent-proxy/` module and may be run as an independent MCP server.

| Category | Tool                | Core Parameters                                                |
| -------- | ------------------- | -------------------------------------------------------------- |
| Proxy    | `proxy_announce`    | `proxyAddress`, `target`, `value`, `data`, `riskTier`, `chain` |
| Proxy    | `proxy_execute`     | `proxyAddress`, `announcementId`, `chain`                      |
| Proxy    | `proxy_cancel`      | `proxyAddress`, `announcementId`, `reason`, `chain`            |
| Proxy    | `proxy_get_pending` | `proxyAddress`, optional `chain`                               |
| Proxy    | `proxy_get_config`  | `proxyAddress`, optional `chain`                               |
| Proxy    | `proxy_configure`   | `proxyAddress`, `configPatch`, `chain`                         |

***

## am-AMM Strategy Auction Tools (5)

Tools for the Harberger lease auction that determines vault management rights. These tools interact with the StrategyAuctionModule (Section 10.16 in [06-contracts.md](/docs/gotts-vaults/vault/06-contracts.md)). Activated when `TOOL_PROFILE` includes `vault`.

| Category | Tool                   | Core Parameters                                    |
| -------- | ---------------------- | -------------------------------------------------- |
| am-AMM   | `vault_bid_management` | `vaultAddress`, `agentId`, `rentPerBlock`, `chain` |
| am-AMM   | `vault_topup_rent`     | `vaultAddress`, `agentId`, `amount`, `chain`       |
| am-AMM   | `vault_withdraw_rent`  | `vaultAddress`, `agentId`, `chain`                 |
| am-AMM   | `vault_get_manager`    | `vaultAddress`, `chain`                            |
| am-AMM   | `vault_evict_manager`  | `vaultAddress`, `agentId`, `chain`                 |

**`vault_bid_management`**: Submit a bid for the right to manage a vault's strategy. Caller must be ERC-8004 registered with minimum reputation (default: Verified tier, score 50+). Bid must exceed current manager's rent by `minBidIncrementBps` (default 5%). Bidder deposits K blocks of rent upfront as collateral. Returns bid status, required collateral, and current manager details.

**`vault_topup_rent`**: Add additional base asset to the bidder's rent collateral, extending management tenure. Returns updated collateral balance and estimated blocks remaining.

**`vault_withdraw_rent`**: Withdraw accumulated rent as a vault depositor. Rent accrues per block from the active manager. Returns the amount withdrawn in base asset units.

**`vault_get_manager`**: Read-only. Returns the current active manager's address, ERC-8004 agent ID, rent rate per block, collateral remaining (in blocks), management start time, and ERC-8004 reputation score.

**`vault_evict_manager`**: Evict a manager whose rent collateral has been exhausted. Callable by any agent. Returns eviction status and remaining collateral (if any).

***

## Deferred Tools (Post-v1)

### Deferred CCA tools (4)

| Tool               | Core Parameters                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `submit_cca_bid`   | `vaultAddress`, `agentId`, `auctionAddress`, `assets`, optional `maxPrice`, `chain`       |
| `exit_cca_bid`     | `vaultAddress`, `agentId`, `auctionAddress`, optional `assets`, `chain`                   |
| `claim_cca_tokens` | `vaultAddress`, `agentId`, `auctionAddress`, `chain`                                      |
| `deploy_liquidity` | `vaultAddress`, `agentId`, `token0`, `token1`, `fee`, `assets`, optional `range`, `chain` |

### Deferred growth tools (4)

| Tool                          | Core Parameters                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| `vault_quick_deposit`         | `vaultAddress`, `assets`, optional `chain`                                                  |
| `vault_get_referral_stats`    | `agentId`, optional `vaultAddress`, optional `chain`                                        |
| `vault_recruit_agent`         | `recruiterAgentId`, optional `candidateAgentId`, `assets`, `vaultAddress`, optional `chain` |
| `vault_get_recruitment_stats` | `agentId`, optional `vaultAddress`, optional `chain`                                        |

***

## Strategy Marketplace Tools (6)

Tools for the agent learning and strategy economy (see [17-learning-economy.md](/docs/gotts-vaults/vault/17-learning-economy.md)). These tools activate when `TOOL_PROFILE` includes `vault` or `marketplace`.

| Category    | Tool                       | Core Parameters                                                                                     |
| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
| Marketplace | `list_strategies`          | `assetClass`, `regimeSuitable`, `minSharpe`, `maxPriceUsdc`, `minReputation`, `limit`, `chain`      |
| Marketplace | `purchase_strategy`        | `strategyId`, `buyerAgentId`, `chain`                                                               |
| Marketplace | `query_agent_reputation`   | `agentId`, `includeStrategyHistory`, `chain`                                                        |
| Marketplace | `subscribe_signals`        | `strategyId`, `buyerAgentId`, `signalTypes`, `chain`                                                |
| Marketplace | `publish_strategy`         | `metadata`, `priceUsdc`, `stakeUsdc`, `sellerAgentId`, `zkProofHash`, `easAttestationHash`, `chain` |
| Marketplace | `claim_strategy_royalties` | `strategyId`, `sellerAgentId`, `chain`                                                              |

**`list_strategies`**: Filtered search of the strategy marketplace. Queries `StrategyMarketplaceRegistry` on-chain, applies alpha decay to prices (`P(t) = P_base × e^(-λt)`), fetches seller reputation from ERC-8004 Reputation Registry, and ranks by `(reputation_weight × sharpe) / decay_adjusted_price`. Returns current prices — callers should not cache results as prices change continuously.

**`purchase_strategy`**: Initiates x402 micropayment flow. Buyer's wallet sends USDC to `StrategyEscrow`. On confirmation, `recordPurchase()` is called on the registry and strategy JSON is fetched from IPFS. Verification: all purchases are covered by an AUM-tiered opML challenge window (24h for vault AUM < $1K, 72h for $1K–$10K, 7 days for > $10K) and an EAS model commitment (`{ modelCID, inputDataHash, claimedOutputHash }` signed by the seller's ERC-8004 key). Public-model strategies can be independently verified via deterministic replay with `onnxruntime-node`. ZK proof (Bionetta/DeepProve) is generated asynchronously only when a dispute is filed — not at purchase time. See [17-learning-economy.md §8](/docs/gotts-vaults/vault/17-learning-economy.md) for the full verification architecture.

**`query_agent_reputation`**: Reads ERC-8004 Reputation Registry for strategy seller agents. Returns reputation tier, score, milestone completions, strategy count, average buyer rating, and slash history. Used by buyers to evaluate seller credibility before purchase.

**`subscribe_signals`**: Returns a WebSocket endpoint and auth token for real-time strategy signals. Buyer must have purchased the strategy first. Signal types: `regime` (\~every 5 minutes), `alpha` and `rebalance` (as generated). Auth token is a signed JWT with 24-hour TTL.

**`publish_strategy`**: Register a new strategy on `StrategyMarketplaceRegistry`. Validates seller has Verified+ reputation (score ≥ 50). Uploads strategy JSON to IPFS. Computes and posts EAS model commitment (`{ modelCID, inputDataHash, claimedOutputHash }` — signed by seller's ERC-8004 key). Locks seller stake in `StrategyEscrow`. Requires sampleSize ≥ 200 episodes across ≥ 2 distinct market regimes and PSR > 0.90. ZK proof is optional at publication; required only on dispute.

**`claim_strategy_royalties`**: Harvest accumulated USDC from strategy sales. Calls `StrategyMarketplaceRegistry.claimRoyalties(strategyId)`. Royalties are available after the 7-day dispute window closes without challenge. The `strategy-marketplace` agent routes proceeds to the `treasury-manager` agent for compounding.

**Updated tool inventory**:

| Scope                         | Count  |
| ----------------------------- | ------ |
| Core v1 vault tools           | 24     |
| Strategy marketplace tools    | 6      |
| am-AMM strategy auction tools | 5      |
| Optional proxy tools          | 6      |
| Deferred tools                | 8      |
| **Roadmap total**             | **49** |

**Error codes for marketplace tools**:

| Error Code                 | Description                                                                |
| -------------------------- | -------------------------------------------------------------------------- |
| `STRATEGY_NOT_FOUND`       | Strategy ID is not registered in `StrategyMarketplaceRegistry`             |
| `INSUFFICIENT_REPUTATION`  | Seller does not meet Verified+ tier (score ≥ 50) for publishing            |
| `INSUFFICIENT_STAKE`       | Seller stake below minimum (`max(10, priceUsdc × subscribersCount × 0.1)`) |
| `MODEL_COMMITMENT_MISSING` | EAS model commitment not posted for this strategy                          |
| `ZK_PROOF_INVALID`         | `verifyPerformanceProof()` returned false on Base (dispute path only)      |
| `SAMPLE_SIZE_INSUFFICIENT` | Performance claims require sampleSize ≥ 200 episodes across ≥ 2 regimes    |
| `STRATEGY_SLASHED`         | Strategy has been slashed due to underperformance dispute                  |
| `DISPUTE_WINDOW_ACTIVE`    | 7-day dispute window has not elapsed; royalties not yet claimable          |
| `NOT_STRATEGY_SELLER`      | Caller is not the registered seller for this strategy                      |

***

## Ownership and Runtime Boundaries

| Surface               | Owner Package                                  | Notes                                                          |
| --------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
| Core vault tools      | `packages/vault` (or vault module in monorepo) | Required for core-v1 release                                   |
| Proxy tools           | `packages/agent-proxy`                         | Optional but strongly recommended for manager/admin operations |
| Deferred CCA tools    | `packages/vault` expansion track               | Enabled in Track A after core safety gates                     |
| Deferred growth tools | `packages/vault` expansion track               | Enabled in Track B after abuse controls are ready              |

***

## Tool and Schema Versioning (Normative)

Vault MCP tools follow the same versioning policy as the core MCP server (see [mcp-server/02-architecture.md](/docs/gotts-safe-mcp-server/mcp-server/02-architecture.md) Section "Tool and Schema Versioning").

* Every vault tool response MUST include `schemaVersion: number` and `deprecated: boolean`.
* Breaking changes to parameter schemas or response shapes MUST ship as a new version; old versions remain for >= 90 days.
* Non-breaking additions (new optional params, new response fields) increment `schemaVersion` without requiring a new tool version.
* Deferred tools (CCA, growth) are not subject to versioning until they ship — they are clearly marked as deferred in this document.
* Core v1 tool schemas are frozen at `schemaVersion: 1` as of this PRD. Any changes require a "Breaking Changes" entry in `CHANGELOG.md`.

***

## Change Control

* Any tool rename, parameter rename, or category move requires coordinated updates to:
  * `00-quickstart.md`
  * `04-architecture.md`
  * `09-agents-skills.md`
  * `agentic-vault-protocol-prd.md`
  * `DRIFT-MATRIX.md`
* Backward-incompatible changes require explicit migration notes in `DECISIONS.md` and a "Breaking Changes" log entry per the versioning policy above.