decision_create

Creates a new decision envelope to track an agent's decision-making process. Every agent operation must start with creating a decision envelope.

Overview

The decision_create method opens a new decision envelope that will track all subsequent operations within that decision context. The decision envelope captures the intent, automation mode, and metadata about the decision.

Request

Parameters

Automation Modes

• propose - Agent suggests an action, human must approve
• approve - Agent can approve actions within policy limits
• override - Human overrides agent decision
• autonomous - Fully automated within policy constraints

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "decision_create",
    "arguments": {
      "intent": "customer.discount.evaluate",
      "automation_mode": "propose",
      "instance": "web-agent-prod-v2",
      "actor": "order-processing-agent",
      "version": "1.2.3",
      "metadata": {
        "customer_id": "1001",
        "discount_requested": "0.15",
        "order_value": 10000
      }
    }
  }
}

Response

Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"decision_id\": \"TMEM_abc123...\", \"status\": \"open\", \"created_at\": \"2026-01-07T12:00:00Z\"}"
      }
    ]
  }
}

The response contains:

• decision_id (string) - Unique identifier for this decision envelope
• status (string) - Current status, typically "open" for newly created decisions
• created_at (string) - ISO 8601 timestamp of when the decision was created

Response Fields

Error Cases

Missing Required Parameters

Error Code: -32600 (Invalid Request)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "intent is required"
  }
}

Common causes:

• Missing intent parameter
• Missing automation_mode parameter

Invalid Automation Mode

Error Code: -32602 (Invalid params)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "automation_mode must be one of: propose, approve, override, autonomous"
  }
}

Authentication Errors

HTTP Status: 401 Unauthorized

Occurs when:

• API key is missing
• API key is invalid
• API key has been revoked

Rate Limiting

HTTP Status: 429 Too Many Requests

Occurs when:

• Exceeding 1000 decisions/hour per agent
• Exceeding 100 requests/second per API key

Response includes Retry-After header indicating when to retry.

Usage Examples

Basic Decision Creation

import requests

response = requests.post('https://mcp.tracemem.com',
    headers={'Authorization': 'Agent YOUR_API_KEY'},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "decision_create",
            "arguments": {
                "intent": "customer.order.create",
                "automation_mode": "propose"
            }
        }
    })

result = response.json()
decision_data = json.loads(result["result"]["content"][0]["text"])
decision_id = decision_data["decision_id"]

Decision with Metadata

response = requests.post('https://mcp.tracemem.com',
    headers={'Authorization': 'Agent YOUR_API_KEY'},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "decision_create",
            "arguments": {
                "intent": "support.ticket.escalate",
                "automation_mode": "autonomous",
                "instance": "support-agent-v1.0",
                "version": "1.0.0",
                "metadata": {
                    "ticket_id": "T-12345",
                    "severity": "high",
                    "customer_tier": "premium"
                }
            }
        }
    })

Best Practices

1. Use meaningful intents: Follow a hierarchical naming pattern like domain.action.subaction (e.g., customer.order.create, inventory.restock.approve)

2. Track instances: Use the instance parameter to distinguish between different deployments (e.g., "prod-v2.3", "staging-v1")

3. Include relevant metadata: Store context that will be useful for auditing and debugging later

4. Always close decisions: After completing operations, use decision_close to commit or rollback the decision

5. Choose appropriate automation mode: Select the mode that matches your agent's authority level and workflow requirements

Related Methods

• decision_get - Retrieve decision status
• decision_close - Close the decision (commit or rollback)
• decision_trace - Get complete decision trace