Skip to content
DeFiPy

defipy.tools

defipy.tools turns analytics primitives into MCP tool definitions. It emits JSON schemas, maintains the registry of what’s exposed, and nothing else. Dispatch logic and pool resolution live in the MCP server (see MCP Demo).

Key exports

  • ToolSpec — frozen dataclass describing one primitive as a tool: name, description, primitive class, JSON input schema, signature parameters
  • TOOL_REGISTRY — dict mapping tool name to ToolSpec. Source of truth for which primitives are exposed.
  • get_schemas(format="mcp") — returns the full list of MCP tool-definition dicts
  • list_tool_names() — returns the sorted list of registered tool names

The 10 curated tools (v2.0)

ToolCategoryProtocol scope
AnalyzePositionPosition AnalysisV2, V3
AnalyzeBalancerPositionPosition AnalysisBalancer
AnalyzeStableswapPositionPosition AnalysisStableswap
SimulatePriceMovePrice ScenariosV2, V3
SimulateBalancerPriceMovePrice ScenariosBalancer
SimulateStableswapPriceMovePrice ScenariosStableswap
CheckPoolHealthPool HealthV2, V3
DetectRugSignalsPool HealthV2, V3
CalculateSlippageExecutionV2, V3
AssessDepegRiskRiskStableswap

Usage

import json
from defipy.tools import get_schemas, list_tool_names, TOOL_REGISTRY


# List the 10 curated tools
print(list_tool_names())


# Get the full MCP schemas
schemas = get_schemas(format="mcp")


# Inspect one tool's schema
check_pool_health = next(s for s in schemas if s["name"] == "CheckPoolHealth")
print(json.dumps(check_pool_health, indent=2))


# Access the registry directly
spec = TOOL_REGISTRY["CheckPoolHealth"]
print(spec.description)
print(spec.input_schema)

Curation principles

Three principles drove the v2.0 tool set:

  • Leaf primitives over composition. AnalyzePosition ships as a tool; AggregatePortfolio does not. An LLM composing AnalyzePosition three times is a better ergonomic fit than a single tool demanding a structured multi-position payload.
  • Protocol parity or graceful degradation. Tools that work across all four AMM families were preferred over tools that force the LLM to understand per-protocol scope limits.
  • Direct question-to-answer mapping. Each tool answers a user-visible question in one call. Tools requiring multi-step reasoning (EvaluateRebalance, CompareProtocols) are deferred to v2.1+.

Dispatch boundary

Dispatch parameters — lp, token_in, depeg_token — are absent from every tool’s input_schema. These are supplied by the MCP server from the user’s chosen pool, not by the LLM. DISPATCH_SUPPLIED_PARAMS is the frozenset that captures this boundary; schema drift tests reference it directly.

Format support

v2.0 supports "mcp" only. get_schemas("anthropic") and get_schemas("openai") raise NotImplementedError with a v2.1 message. Both formats are derivable from MCP schemas with small envelope wrappers. See Binding to Other LLMs.

For the full tool-schema walkthrough, see Tool Schemas. For the curation roadmap, see the Roadmap.