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
tool_input	object	Yes	Input parameters passed to the tool
tool_output	object	No	Output returned by the tool
execution_time_ms	int	No	Execution time in milliseconds
success	bool	No	Whether call succeeded (default: true)
error_message	string	No	Error details if call failed
session_id	string	No	Associated chat session
space_id	string	No	Memory space
timestamp	datetime	No	When the tool was called
store_as_memory	bool	No	Also create a memory from this call

Example

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

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_only	bool	Filter to successful calls only
limit	int	Items per page (default 50)
offset	int	Number of items to skip

Example

curl "https://memoryapi.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