tool_usage_format.md•3.82 kB
# Tool Usage Format Specification
This document provides a comprehensive specification for the `tool_usage` parameter used in various parts of the Chroma MCP Server, particularly in the `chroma_log_chat` tool and related functionality.
**Document Purpose:** This is the canonical reference for the tool_usage format across the entire codebase. While individual tool documentation (like [`log-chat.md`](docs/scripts/log-chat.md)) may include basic usage examples, this specification covers all details, edge cases, and technical implementation aspects.
## Standard Format
The `tool_usage` parameter is an array of objects, where each object MUST follow this structure:
```json
{
"name": "tool_name",
"args": {
"param1": "value1",
"param2": "value2",
...
}
}
```
### Required Fields
- `name` (string): The name of the tool that was used (e.g., "read_file", "edit_file", "codebase_search").
### Optional Fields
- `args` (object): A JSON object containing the arguments passed to the tool. This field is optional but recommended for comprehensive logging.
## Examples
### Basic Example
```json
[
{"name": "read_file", "args": {"target_file": "src/config.js"}},
{"name": "edit_file", "args": {"target_file": "src/config.js"}}
]
```
### Complex Example
```json
[
{"name": "codebase_search", "args": {"query": "JWT authentication", "target_directories": ["src/auth"]}},
{"name": "read_file", "args": {"target_file": "src/auth/jwt.js", "offset": 10, "limit": 50}},
{"name": "edit_file", "args": {"target_file": "src/auth/jwt.js", "instructions": "Update token expiration"}}
]
```
## Programmatic Usage
When constructing the `tool_usage` list in code:
```python
tool_usage = [
{"name": "read_file", "args": {"target_file": "file.txt"}},
{"name": "edit_file", "args": {"target_file": "file.txt", "instructions": "Update content"}}
]
```
## Command Line Usage
When using with the `chroma-mcp-client log-chat` command:
```bash
--tool-usage '[{"name": "read_file", "args": {"target_file": "file.txt"}}, {"name": "edit_file", "args": {"target_file": "file.txt"}}]'
```
## Legacy/Deprecated Format
> **Note:** This format is deprecated and will be removed in a future version.
For backward compatibility, the system currently also accepts an alternative format:
```json
{
"tool": "tool_name",
"params": {
"param1": "value1",
"param2": "value2",
...
}
}
```
However, using this format will generate warnings, and it's recommended to migrate to the standard format with `name` and `args` keys.
## Technical Details
The `tool_usage` parameter is used in multiple places:
1. **Auto Log Chat Rule**: The rule instructs AI assistants to log their tool usage during interactions.
2. **ChromaDB Storage**: The tool usage is processed and stored in the `chat_history_v1` collection.
3. **Analysis**: Tool sequences are derived from this data for pattern analysis and learning extraction.
### Processing
During processing:
1. The tool names are extracted to form a `tool_sequence` string (e.g., "read_file→edit_file→run_terminal_cmd").
2. This sequence helps identify problem-solving patterns and aids in confidence scoring.
3. The sequence may be used for reinforcement learning in later phases.
## Troubleshooting
If you encounter errors related to the `tool_usage` parameter:
1. **Validation Error**: Ensure each item in the array has a `name` key.
2. **Missing Required Fields**: Check that every object includes at least the `name` field.
3. **Format Issues**: Verify the JSON structure is valid with properly formatted arrays and objects.
## Related Documentation
- [API Reference - chroma_log_chat](../api_reference.md#chroma_log_chat)
- [Enhanced Context Capture](./enhanced_context_capture.md)
- [Log Chat Script](docs/scripts/log-chat.md)