Tool Call Tracking API

Track AI agent tool invocations as memories.

Overview

Tool Call Tracking records your AI agent's tool usage as first-class memories:

• Track which tools were called and with what parameters
• Store tool results for future reference
• Analyze tool usage patterns
• Enable your AI to learn from past tool interactions

Record Tool Call

POST /v1/tools/calls

Request Body

Field	Type	Required	Description
tool_name	string	Yes	Name of the tool
parameters	object	No	Input parameters
result	object	No	Tool execution result
session_id	string	No	Associated chat session
space_id	string	No	Memory space
duration_ms	int	No	Execution time
success	bool	No	Whether call succeeded

Example

curl -X POST https://api.memory.tensorheart.com/v1/tools/calls \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "search_database",
    "parameters": {"query": "user preferences"},
    "result": {"count": 5, "items": [...]},
    "success": true,
    "duration_ms": 150
  }'

Response

{
  "success": true,
  "data": {
    "id": "call_abc123",
    "tool_name": "search_database",
    "success": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

---

List Tool Calls

GET /v1/tools/calls

Query Parameters

Parameter	Type	Description
tool_name	string	Filter by tool name
session_id	string	Filter by session
success	bool	Filter by success status
page	int	Page number
per_page	int	Items per page

Example

curl "https://api.memory.tensorheart.com/v1/tools/calls?tool_name=search_database" \
  -H "Authorization: Bearer $API_KEY"

---

Get Tool Call

GET /v1/tools/calls/{call_id}

---

Get Tool Summary

Get aggregated statistics about tool usage.

GET /v1/tools/summary

Response

{
  "success": true,
  "data": {
    "total_calls": 1523,
    "success_rate": 0.97,
    "tools": [
      {
        "name": "search_database",
        "call_count": 890,
        "avg_duration_ms": 145,
        "success_rate": 0.99
      },
      {
        "name": "send_email",
        "call_count": 234,
        "avg_duration_ms": 520,
        "success_rate": 0.95
      }
    ]
  }
}

Use Cases

• Debugging - Trace what tools your agent called and why
• Optimization - Identify slow or frequently failing tools
• Learning - Let your AI reference past tool results
• Auditing - Maintain a complete history of agent actions