products_list
Lists all data products available to the agent, including their permissions and allowed purposes.
Overview
The products_list method returns a list of data products that the agent can access. This is useful for discovering what data is available and understanding what operations (read/write) are permitted.
Request
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
purpose | string | No | Filter products by purpose (only return products that allow this purpose) |
Example Request - List All Products
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "products_list",
"arguments": {}
}
}
Example Request - Filter by Purpose
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "products_list",
"arguments": {
"purpose": "order_processing"
}
}
}
Response
Success Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"products\": [{\"product_id\": \"pg_customers_v1\", \"name\": \"Customer Accounts\", \"permissions\": [\"read\"], \"purposes\": [\"order_processing\", \"support\"]}]}"
}
]
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
products | array | Array of data product summaries |
products[].product_id | string | Unique identifier for the data product |
products[].name | string | Human-readable name of the data product |
products[].permissions | array | List of permissions: "read", "write", or both |
products[].purposes | array | List of allowed purposes for this data product |
Example Response
{
"products": [
{
"product_id": "pg_customers_v1",
"name": "Customer Accounts",
"permissions": ["read"],
"purposes": ["order_processing", "support", "marketing"]
},
{
"product_id": "pg_orders_v1",
"name": "Order Management",
"permissions": ["read", "write"],
"purposes": ["order_processing", "order_fulfillment"]
},
{
"product_id": "pg_inventory_v1",
"name": "Inventory Data",
"permissions": ["read"],
"purposes": ["order_validation", "inventory_check"]
}
]
}
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
List All Available Products
import requests
import json
def list_products(purpose=None, api_key=None):
args = {}
if purpose:
args["purpose"] = purpose
response = requests.post('https://mcp.tracemem.com',
headers={'Authorization': f'Agent {api_key}'},
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "products_list",
"arguments": args
}
})
result = response.json()
if "error" in result:
raise Exception(result["error"]["data"])
products_data = json.loads(result["result"]["content"][0]["text"])
return products_data
# List all products
products = list_products(api_key="YOUR_API_KEY")
for product in products["products"]:
print(f"{product['name']} ({product['product_id']})")
print(f" Permissions: {', '.join(product['permissions'])}")
print(f" Purposes: {', '.join(product['purposes'])}")
Filter Products by Purpose
# Find products that support order processing
order_products = list_products(purpose="order_processing", api_key=api_key)
print("Products available for order processing:")
for product in order_products["products"]:
print(f"- {product['name']} ({product['product_id']})")
Find Products with Write Access
# List all products
all_products = list_products(api_key=api_key)
# Filter for write-enabled products
write_products = [
p for p in all_products["products"]
if "write" in p["permissions"]
]
print("Products with write access:")
for product in write_products:
print(f"- {product['name']} ({product['product_id']})")
Discover Available Data
def discover_data_capabilities(api_key):
"""Discover what data the agent can access"""
products = list_products(api_key=api_key)
capabilities = {
"read_only": [],
"read_write": [],
"purposes": set()
}
for product in products["products"]:
if "write" in product["permissions"]:
capabilities["read_write"].append(product["product_id"])
else:
capabilities["read_only"].append(product["product_id"])
capabilities["purposes"].update(product["purposes"])
capabilities["purposes"] = list(capabilities["purposes"])
return capabilities
# Discover capabilities
caps = discover_data_capabilities(api_key)
print(f"Read-only products: {caps['read_only']}")
print(f"Read-write products: {caps['read_write']}")
print(f"Available purposes: {caps['purposes']}")
Best Practices
-
Discover on startup: List available products when your agent starts to understand what data is accessible
-
Filter by purpose: Use the
purposeparameter to find products relevant to your use case -
Check permissions: Verify that products have the required permissions (read/write) before using them
-
Cache results: Product lists don't change frequently, so you can cache results to reduce API calls
-
Use with product_get: After listing products, use
product_getto get detailed information about specific products -
Handle empty results: Be prepared for cases where no products match your criteria
Important Notes
-
Agent-specific: The list only includes products that your agent has permission to access
-
Permissions are explicit: Products only appear if you have at least read permission
-
Purpose filtering: When filtering by purpose, only products that explicitly allow that purpose are returned
-
No detailed schema: This method returns summaries only. Use
product_getfor detailed schema information -
Real-time: The list reflects current permissions and may change if permissions are updated
Related Methods
product_get- Get detailed information about a specific data productcapabilities_get- Get agent capabilities and permissionsdecision_read- Read data from a data productdecision_write- Write data to a data product