Tools

POST /v1/tools/call

Call any System R tool by name. This is the universal tool execution endpoint.

curl -X POST https://agents.systemr.ai/v1/tools/call \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "calculate_position_size",
    "arguments": {
      "equity": "100000",
      "entry_price": "185.50",
      "stop_price": "180.00",
      "direction": "long"
    }
  }'

Request body

Field	Type	Required	Description
tool_name	string	Yes	Tool name (e.g. "calculate_position_size").
arguments	object	No	Tool-specific arguments. Default: empty object.

Response (200)

{
  "tool_name": "calculate_position_size",
  "result": {
    "shares": 363,
    "risk_amount": "2000.00",
    "risk_percent": "0.02",
    "notional": "67351.50",
    "one_r_dollars": "2000.00",
    "direction": "long"
  }
}

Error responses

400 - Invalid arguments:

{
  "detail": "Missing required argument: equity"
}

402 - Insufficient balance:

{
  "detail": "Insufficient balance. Required: $0.003, Available: $0.001"
}

404 - Unknown tool:

{
  "detail": "Unknown tool: 'fake_tool'. Available: analyze_correlations, analyze_confidence, ..."
}

Example: Monte Carlo

curl -X POST https://agents.systemr.ai/v1/tools/call \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "run_monte_carlo",
    "arguments": {
      "r_multiples": ["1.5", "-1.0", "2.3", "-0.5", "1.8", "-1.0", "3.2"],
      "starting_equity": "100000",
      "num_simulations": 5000
    }
  }'

Example: Detect patterns

curl -X POST https://agents.systemr.ai/v1/tools/call \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "detect_patterns",
    "arguments": {
      "bars": [
        {"open": "150.00", "high": "152.00", "low": "149.50", "close": "151.50", "volume": "5000000"},
        {"open": "151.50", "high": "153.00", "low": "150.00", "close": "152.80", "volume": "4500000"}
      ]
    }
  }'

---

GET /v1/tools/list

List all available tools with descriptions, pricing, and input schemas. No authentication required.

curl https://agents.systemr.ai/v1/tools/list

Response (200)

{
  "tool_count": 55,
  "tools": [
    {
      "name": "calculate_position_size",
      "description": "Calculate optimal position size using the G-formula...",
      "cost_usdc": "0.003",
      "input_schema": {
        "type": "object",
        "properties": {
          "equity": {"type": "string", "description": "Account equity in USD"},
          "entry_price": {"type": "string", "description": "Planned entry price"},
          "stop_price": {"type": "string", "description": "Stop loss price"},
          "direction": {"type": "string", "enum": ["long", "short"]}
        },
        "required": ["equity", "entry_price", "stop_price", "direction"]
      }
    },
    {
      "name": "get_pricing",
      "description": "Get current pricing for all System R operations...",
      "cost_usdc": "free",
      "input_schema": {"type": "object", "properties": {}}
    }
  ]
}

Each tool entry includes:

Field	Description
name	Tool name used in tool_name field of /v1/tools/call.
description	Human-readable description of what the tool does and its cost.
cost_usdc	Cost per call as a string (e.g. "0.003") or "free".
input_schema	JSON Schema describing the tool’s input parameters.

Use the input_schema to understand required vs optional parameters, types, and valid enum values for each tool.