decision_evaluate

Evaluates a policy within a decision context to determine if an action is allowed, denied, or requires human approval.

Overview

The decision_evaluate method checks whether a proposed action complies with a policy. Policies define business rules, compliance requirements, and governance constraints. The evaluation returns one of three outcomes: allow, deny, or requires_exception.

Request

Parameters

Parameter	Type	Required	Description
`decision_id`	string	Yes	The decision ID (from `decision_create`)
`policy_id`	string	Yes	Policy identifier (e.g., "discount_cap_v1")
`inputs`	object	Yes*	Policy inputs (data needed for evaluation)
`inputs_ref`	string	No	Reference to a prior read event to use as inputs

* Either inputs or inputs_ref must be provided.

Example Request

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "decision_evaluate",
    "arguments": {
      "decision_id": "TMEM_abc123...",
      "policy_id": "discount_cap_v1",
      "inputs": {
        "proposed_discount": 0.15,
        "customer_tier": "premium",
        "order_value": 10000
      }
    }
  }
}

Using inputs_ref

Instead of providing inputs directly, you can reference a prior read event:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "decision_evaluate",
    "arguments": {
      "decision_id": "TMEM_abc123...",
      "policy_id": "discount_cap_v1",
      "inputs_ref": "evt_read_abc123"
    }
  }
}

Response

Success Response

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"event_id\": \"evt_...\", \"policy_id\": \"discount_cap_v1\", \"outcome\": \"allow\", \"rationale\": {\"message\": \"Discount within policy limits\"}}"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`event_id`	string	Unique identifier for this evaluation event
`policy_id`	string	The policy that was evaluated
`outcome`	string	Evaluation result: `"allow"`, `"deny"`, or `"requires_exception"`
`rationale`	object	Explanation of the evaluation result
`rationale.message`	string	Human-readable explanation

Example Responses

Allow Outcome:

json

{
  "event_id": "evt_eval_abc123",
  "policy_id": "discount_cap_v1",
  "outcome": "allow",
  "rationale": {
    "message": "Discount within policy limits"
  }
}

Deny Outcome:

json

{
  "event_id": "evt_eval_abc123",
  "policy_id": "discount_cap_v1",
  "outcome": "deny",
  "rationale": {
    "message": "Discount exceeds maximum allowed for customer tier"
  }
}

Requires Exception Outcome:

json

{
  "event_id": "evt_eval_abc123",
  "policy_id": "discount_cap_v1",
  "outcome": "requires_exception",
  "rationale": {
    "message": "Discount requires manager approval"
  }
}

Policy Outcomes

`allow`

The policy permits the action. You can proceed with the operation.

Next steps:

Proceed with the intended action (e.g., write data, apply discount)
No approval required

`deny`

The policy blocks the action. You should not proceed.

Next steps:

Do not perform the action
Consider closing the decision with action: "abort"
Log the denial for audit purposes

`requires_exception`

The policy requires human approval before proceeding.

Next steps:

Use decision_request_approval to request approval
Wait for approval (poll decision_get to check status)
Proceed only if approved, otherwise abort

Error Cases

Missing Required Parameters

Error Code: -32600 (Invalid Request)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "decision_id and policy_id are required"
  }
}

Missing Inputs

Error Code: -32600 (Invalid Request)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "Either inputs or inputs_ref must be provided"
  }
}

Policy Not Found

Error Code: -32603 (Internal error)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Policy 'discount_cap_v1' not found or not accessible"
  }
}

Common causes:

Policy doesn't exist
Agent doesn't have permission to evaluate this policy
Policy ID is misspelled

Invalid Inputs

Error Code: -32602 (Invalid params)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Policy inputs validation failed: missing required field 'customer_tier'"
  }
}

Invalid Inputs Reference

Error Code: -32603 (Internal error)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Inputs reference 'evt_read_abc123' not found in decision"
  }
}

Decision Not Found

Error Code: -32603 (Internal error)

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Decision not found"
  }
}

Permission Denied

HTTP Status: 403 Forbidden

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Permission denied: agent does not have permission to evaluate this policy"
  }
}

Authentication Errors

HTTP Status: 401 Unauthorized

Occurs when:

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

Usage Examples

Evaluate Policy Before Action

python

import requests
import json

def evaluate_policy(decision_id, policy_id, inputs=None, inputs_ref=None, api_key=None):
    args = {
        "decision_id": decision_id,
        "policy_id": policy_id
    }
    
    if inputs_ref:
        args["inputs_ref"] = inputs_ref
    elif inputs:
        args["inputs"] = inputs
    else:
        raise ValueError("Either inputs or inputs_ref must be provided")
    
    response = requests.post('https://mcp.tracemem.com',
        headers={'Authorization': f'Agent {api_key}'},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "decision_evaluate",
                "arguments": args
            }
        })
    
    result = response.json()
    if "error" in result:
        raise Exception(result["error"]["data"])
    
    eval_data = json.loads(result["result"]["content"][0]["text"])
    return eval_data

# Evaluate discount policy
result = evaluate_policy(
    decision_id="TMEM_abc123...",
    policy_id="discount_cap_v1",
    inputs={
        "proposed_discount": 0.15,
        "customer_tier": "premium",
        "order_value": 10000
    },
    api_key="YOUR_API_KEY"
)

# Handle outcome
if result["outcome"] == "allow":
    print("Policy allows this action")
    # Proceed with action
elif result["outcome"] == "deny":
    print(f"Policy denies this action: {result['rationale']['message']}")
    # Abort decision
elif result["outcome"] == "requires_exception":
    print("Approval required")
    # Request approval

Using Inputs Reference

python

# First, read customer data
read_result = read_data(
    decision_id=decision_id,
    product="pg_customers_v1",
    purpose="discount_evaluation",
    query={"customer_id": "1001"},
    api_key=api_key
)

# Use the read event as inputs for policy evaluation
eval_result = evaluate_policy(
    decision_id=decision_id,
    policy_id="discount_cap_v1",
    inputs_ref=read_result["event_id"],  # Reference the read event
    api_key=api_key
)

Complete Workflow with Policy Evaluation

python

# Create decision
decision = create_decision(
    intent="customer.discount.evaluate",
    automation_mode="propose",
    api_key=api_key
)
decision_id = decision["decision_id"]

# Read customer data
customer = read_data(
    decision_id=decision_id,
    product="pg_customers_v1",
    purpose="discount_evaluation",
    query={"customer_id": "1001"},
    api_key=api_key
)

# Evaluate policy
policy_result = evaluate_policy(
    decision_id=decision_id,
    policy_id="discount_cap_v1",
    inputs={
        "proposed_discount": 0.25,
        "customer_tier": customer["records"][0]["tier"],
        "order_value": 10000
    },
    api_key=api_key
)

# Handle outcome
if policy_result["outcome"] == "allow":
    # Apply discount
    write_data(
        decision_id=decision_id,
        product="pg_orders_v1",
        purpose="order_creation",
        mutation={"operation": "insert", "records": [...]},
        api_key=api_key
    )
    close_decision(decision_id, "commit", api_key=api_key)
    
elif policy_result["outcome"] == "deny":
    # Reject discount
    close_decision(decision_id, "abort", 
                  reason=policy_result["rationale"]["message"],
                  api_key=api_key)
    
elif policy_result["outcome"] == "requires_exception":
    # Request approval
    request_approval(
        decision_id=decision_id,
        title="Discount Approval Required",
        message=f"Customer requesting {policy_result['rationale']['message']}",
        api_key=api_key
    )
    # Poll for approval...

Best Practices

Evaluate before actions: Always evaluate relevant policies before performing actions (especially writes)
Handle all outcomes: Be prepared to handle allow, deny, and requires_exception outcomes appropriately
Use inputs_ref when possible: Reference prior read events to avoid duplicating data and ensure consistency
Check policy requirements: Understand what inputs each policy requires before calling
Log evaluations: Policy evaluations are automatically logged, but you may want to log outcomes in your application
Respect deny outcomes: Never proceed with an action when policy evaluation returns deny
Request approval promptly: When requires_exception is returned, request approval immediately
Provide context in approvals: When requesting approval after requires_exception, include the policy rationale in your approval message

Important Notes

All evaluations are logged: Every policy evaluation is recorded in the decision trace
Policies are tenant-specific: Policies are configured per tenant and may vary
Inputs validation: Policy inputs are validated against the policy's schema
Outcomes are deterministic: The same inputs to the same policy will always produce the same outcome
Policy changes: If a policy is updated, new evaluations may produce different outcomes
Required for some writes: Some data products require policy evaluation before writes are allowed

Related Methods

decision_create - Create a decision (required before evaluation)
decision_request_approval - Request approval when outcome is requires_exception
decision_write - Write data (may require policy evaluation first)
decision_get - Check decision status (useful after requesting approval)

decision_evaluate

Overview

Request

Parameters

Example Request

Using inputs_ref

Response

Success Response

Response Fields

Example Responses

Policy Outcomes

`allow`

`deny`

`requires_exception`

Error Cases

Missing Required Parameters

Missing Inputs

Policy Not Found

Invalid Inputs

Invalid Inputs Reference

Decision Not Found

Permission Denied

Authentication Errors

Usage Examples

Evaluate Policy Before Action

Using Inputs Reference

Complete Workflow with Policy Evaluation

Best Practices

Important Notes

Related Methods

Related Topics

Next Steps