tools/<tool_name>/
├── __init__.py       # Main implementation (REQUIRED)
├── README.md         # Documentation (REQUIRED)
├── manifest.json     # Tool metadata (recommended)
└── tests/
    ├── __init__.py
    └── test_<tool>.py

"""
Tool Name - Brief description.

Usage:
    from tools.tool_name import main_function
    result = main_function(arg1, arg2)

CLI:
    valor-tool-name arg1 arg2
"""

import argparse
import sys
from pathlib import Path

# Import model constants if using AI
# from config.models import MODEL_FAST, MODEL_REASONING

def main_function(arg1: str, arg2: str | None = None) -> dict:
    """
    Main tool function.

    Args:
        arg1: Description
        arg2: Optional description

    Returns:
        dict with 'result' key on success, 'error' key on failure
    """
    try:
        # Implementation
        result = do_work(arg1, arg2)
        return {"result": result}
    except Exception as e:
        return {"error": str(e)}


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(description="Tool description")
    parser.add_argument("arg1", help="First argument")
    parser.add_argument("arg2", nargs="?", help="Optional second argument")
    args = parser.parse_args()

    result = main_function(args.arg1, args.arg2)

    if "error" in result:
        print(f"Error: {result['error']}", file=sys.stderr)
        sys.exit(1)

    print(result["result"])


if __name__ == "__main__":
    main()

{
  "name": "tool-name",
  "version": "1.0.0",
  "description": "What this tool does",
  "type": "library",
  "status": "beta",
  "source": {"type": "internal"},
  "capabilities": ["capability1", "capability2"],
  "requires": {
    "env": ["API_KEY_NAME"],
    "python": ">=3.11"
  }
}

valor-tool-name = "tools.tool_name:main"

pip install -e .

- **Tool Name** (`valor-tool-name`): Brief description
  ```bash
  valor-tool-name arg1 arg2    # Example usage
  valor-tool-name --help       # Show options

#### Bridge Integration (if tool outputs files)

Files are auto-detected by `extract_files_from_response()` in the bridge.

For explicit file sending, use the marker:

Check `ABSOLUTE_PATH_PATTERN` in `bridge/telegram_bridge.py` covers your file types.

#### Model Configuration (if using AI)

Import from `config/models.py`:
- `MODEL_FAST` - Quick responses (haiku-class)
- `MODEL_REASONING` - Complex tasks (sonnet-class)
- `MODEL_IMAGE_GEN` - Image generation
- `MODEL_VISION` - Image analysis

Add new constants if needed for specialized models.

### Phase 4: Testing

Create test file at `tools/<tool_name>/tests/test_<tool>.py`:

```python
"""Tests for tool_name."""

import os
import pytest
from tools.tool_name import main_function


class TestToolName:
    """Test suite for tool_name."""

    def test_basic_functionality(self):
        """Test happy path."""
        result = main_function("test_input")
        assert "error" not in result
        assert "result" in result

    @pytest.mark.skipif(
        not os.environ.get("REQUIRED_API_KEY"),
        reason="API key not set"
    )
    def test_real_api_call(self):
        """Test with real API (requires key)."""
        result = main_function("real_input")
        assert "error" not in result

    def test_error_handling(self):
        """Test error cases."""
        result = main_function("")
        # Should handle gracefully
        assert isinstance(result, dict)

pytest tools/<tool_name>/tests/ -v

valor-tool-name --help
valor-tool-name test_arg

# Format and lint
black tools/<tool_name>/
ruff check tools/<tool_name>/

# Commit
git add tools/<tool_name>/ pyproject.toml CLAUDE.md
git commit -m "Add valor-<name> tool for <purpose>"
git push

# Reinstall to register CLI
pip install -e .

# Restart bridge if bridge-integrated
pkill -f telegram_bridge.py
./scripts/start_bridge.sh

# Test in production
# Send test message via Telegram