capabilities_get
Gets the agent's runtime capabilities, including available data products, policies, and permissions.
Overview
The capabilities_get method returns comprehensive information about what your agent can do, including all accessible data products, evaluable policies, and overall permissions. This is useful for understanding your agent's capabilities at runtime.
Request
Parameters
None. This method takes no parameters.
Example Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "capabilities_get",
"arguments": {}
}
}
Response
Success Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"agent_id\": \"agent_...\", \"name\": \"Order Processing Agent\", \"permissions\": {\"data_products\": [...], \"policies\": [...]}}"
}
]
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
agent_id | string | Unique identifier for the agent |
name | string | Human-readable agent name |
permissions | object | Permissions and capabilities |
permissions.data_products | array | List of accessible data products with permissions |
permissions.policies | array | List of evaluable policies |
Example Response
{
"agent_id": "agent_abc123",
"name": "Order Processing Agent",
"permissions": {
"data_products": [
{
"product_id": "pg_customers_v1",
"permissions": ["read"],
"purposes": ["order_processing", "support"]
},
{
"product_id": "pg_orders_v1",
"permissions": ["read", "write"],
"purposes": ["order_processing", "order_fulfillment"]
}
],
"policies": [
{
"policy_id": "discount_cap_v1",
"name": "Discount Cap Policy"
},
{
"policy_id": "order_validation_v1",
"name": "Order Validation Policy"
}
]
}
}
Error Cases
Authentication Errors
HTTP Status: 401 Unauthorized
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": "Unauthorized"
}
}
Occurs when:
- API key is missing
- API key is invalid
- API key has been revoked
Permission Denied
HTTP Status: 403 Forbidden
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": "Permission denied"
}
}
Usage Examples
Get Agent Capabilities
import requests
import json
def get_capabilities(api_key=None):
response = requests.post('https://mcp.tracemem.com',
headers={'Authorization': f'Agent {api_key}'},
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "capabilities_get",
"arguments": {}
}
})
result = response.json()
if "error" in result:
raise Exception(result["error"]["data"])
capabilities_data = json.loads(result["result"]["content"][0]["text"])
return capabilities_data
# Get capabilities
caps = get_capabilities(api_key="YOUR_API_KEY")
print(f"Agent: {caps['name']} ({caps['agent_id']})")
print(f"Data products: {len(caps['permissions']['data_products'])}")
print(f"Policies: {len(caps['permissions']['policies'])}")
Discover Available Operations
def discover_operations(api_key):
"""Discover what operations the agent can perform"""
caps = get_capabilities(api_key)
operations = {
"can_read": [],
"can_write": [],
"can_evaluate": []
}
# Check data product permissions
for product in caps["permissions"]["data_products"]:
if "read" in product["permissions"]:
operations["can_read"].append(product["product_id"])
if "write" in product["permissions"]:
operations["can_write"].append(product["product_id"])
# Check policy permissions
for policy in caps["permissions"]["policies"]:
operations["can_evaluate"].append(policy["policy_id"])
return operations
# Discover operations
ops = discover_operations(api_key)
print(f"Can read from: {ops['can_read']}")
print(f"Can write to: {ops['can_write']}")
print(f"Can evaluate: {ops['can_evaluate']}")
Validate Capabilities Before Operations
def validate_capability(api_key, operation, resource_id):
"""Validate that agent can perform an operation"""
caps = get_capabilities(api_key)
if operation == "read":
products = [p["product_id"] for p in caps["permissions"]["data_products"]
if "read" in p["permissions"]]
if resource_id not in products:
raise ValueError(f"Cannot read from product '{resource_id}'")
elif operation == "write":
products = [p["product_id"] for p in caps["permissions"]["data_products"]
if "write" in p["permissions"]]
if resource_id not in products:
raise ValueError(f"Cannot write to product '{resource_id}'")
elif operation == "evaluate":
policies = [p["policy_id"] for p in caps["permissions"]["policies"]]
if resource_id not in policies:
raise ValueError(f"Cannot evaluate policy '{resource_id}'")
return True
# Validate before operations
try:
validate_capability(api_key, "read", "pg_customers_v1")
# Proceed with read
except ValueError as e:
print(f"Error: {e}")
Build Capability Summary
def build_capability_summary(api_key):
"""Build a human-readable summary of agent capabilities"""
caps = get_capabilities(api_key)
summary = {
"agent_name": caps["name"],
"agent_id": caps["agent_id"],
"data_access": {
"read_only_products": [],
"read_write_products": [],
"total_products": len(caps["permissions"]["data_products"])
},
"policies": {
"count": len(caps["permissions"]["policies"]),
"policy_ids": [p["policy_id"] for p in caps["permissions"]["policies"]]
}
}
for product in caps["permissions"]["data_products"]:
if "write" in product["permissions"]:
summary["data_access"]["read_write_products"].append(product["product_id"])
else:
summary["data_access"]["read_only_products"].append(product["product_id"])
return summary
# Build summary
summary = build_capability_summary(api_key)
print(f"Agent: {summary['agent_name']}")
print(f"Total products: {summary['data_access']['total_products']}")
print(f"Read-write products: {len(summary['data_access']['read_write_products'])}")
print(f"Available policies: {summary['policies']['count']}")
Best Practices
-
Check on startup: Get capabilities when your agent starts to understand what it can do
-
Validate before operations: Check capabilities before attempting operations to provide better error messages
-
Cache capabilities: Capabilities don't change frequently, so cache results to reduce API calls
-
Handle changes: Be prepared for capabilities to change if permissions are updated
-
Use for discovery: Use capabilities to discover available resources dynamically
-
Log capabilities: Log capabilities for debugging and understanding agent behavior
-
Compare with products_list: Use both methods -
capabilities_getfor overview,products_listfor detailed product info
Important Notes
-
Runtime information: Capabilities reflect current permissions and may change if permissions are updated
-
Agent-specific: Capabilities are specific to your agent and API key
-
Summary view: This method provides a summary. Use
products_listandproduct_getfor detailed information -
Permissions are explicit: Only resources you have explicit permission to access are included
-
Real-time: Capabilities reflect the current state and may differ from what was available earlier
Related Methods
products_list- List all available data products (detailed)product_get- Get detailed information about a specific data productdecision_evaluate- Evaluate a policy (requires policy in capabilities)decision_read- Read data (requires product in capabilities)decision_write- Write data (requires product with write permission in capabilities)