tool-creator

# Tool Creator

A skill for creating new agent tools and upgrading existing ones.

Tools are Python functions decorated with `@tool` from `langchain_core.tools` that the agent can call directly during conversations. Unlike skills (which are instruction documents), tools are executable code that extend the agent's capabilities.

## Tool Format

Every tool MUST follow this exact pattern to be compatible with the deepagents framework:

```python
import logging
from langchain_core.tools import tool

logger = logging.getLogger(__name__)


@tool
def my_tool_name(param1: str, param2: int) -> str:
    """Clear description of what this tool does.

    Provide enough detail so the agent knows WHEN and HOW to use this tool.
    The docstring is the primary mechanism for the agent to decide whether to call it.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of what is returned
    """
    logger.info(f"[my_tool_name] params: param1={param1}, param2={param2}")

    # Tool logic here
    result = f"Processed {param1} with {param2}"

    logger.info(f"[my_tool_name] result: {result}")
    return result
```

### Critical Rules

1. **One tool per file**: Each `.py` file in the Tools directory should contain exactly one `@tool` function.
2. **File name = function name**: The file should be named after the tool function (e.g., `my_tool_name.py` contains `def my_tool_name(...)`).
3. **Type hints are required**: All parameters and return types must have type annotations.
4. **Docstring is essential**: The docstring serves as the tool's description for the agent. Write it clearly — it determines when and how the agent will use the tool.
5. **Use logging**: Always log inputs and outputs using the `logger` for debugging.
6. **Tools run in the sandbox**: All `@tool` functions execute in the sandbox container — the same environment where test scripts run. This means the testing environment IS the production environment. You can import any package available in the sandbox.
7. **Pure functions preferred**: Tools should ideally be stateless. If state is needed, use file I/O or external services.
8. **Return serializable types**: Return `str`, `int`, `float`, `bool`, `dict`, or `list` — types that can be serialized in the agent's conversation.

### Available Packages (Sandbox Environment)

All `@tool` functions execute in the **sandbox container** — the same environment where test scripts run. The following packages are pre-installed:

- Python standard library (json, os, re, math, datetime, pathlib, etc.)
- `httpx` — HTTP client for API calls
- `pydantic` — Data validation
- `langchain_core` — Required for `@tool` decorator
- `pyyaml` — YAML parsing
- `seekr_sdk` — Provides `web_search`, `web_crawl`, `web_crawl_many` for internet search and page crawling. When writing `@tool` functions that need to search the web or crawl pages, **always prefer `seekr_sdk` over raw `httpx` calls**. See the "Web-Enabled Tool (using seekr_sdk)" example below.

Since tools run in the same sandbox where you test them, **if your test passes in the sandbox, the tool will also work in production**. If a tool needs a package not in this list, install it in the sandbox Dockerfile (docker-compose.yml sandbox service).

### Docstring Writing Guide

The docstring is how the agent decides whether to call a tool. Good docstrings:

- **First line**: A concise summary of what the tool does (this appears in tool listings)
- **Body**: Explain when to use this tool, what scenarios it covers, and any important constraints
- **Args section**: Describe each parameter with its expected format and examples
- **Returns section**: Describe the return value and its format

Make descriptions specific and "pushy" enough that the agent reliably triggers the tool for relevant tasks. For example:

Bad: `"""Calculate a score."""`

Good: `"""根据身高、体重、年龄计算人物综合打分。该工具根据人的身体数据进行综合评估打分，包括BMI健康指数评分和年龄评分。"""`

---

## Mode 1: Creating a New Tool

When the user wants to create a new tool from scratch or convert a script into a tool:

### Step 1: Understand Requirements

Ask the user:
1. What should this tool do? What problem does it solve?
2. What inputs does it need? (parameter names, types, examples)
3. What should it return? (type, format)
4. Does it need external API calls or only local computation?
5. Are there edge cases or error conditions to handle?

If the user already has a script or describes the logic clearly, extract the answers from context.

### Step 2: Write the Tool (as @tool from the start)

**CRITICAL**: Write the code directly as an `@tool` function from the very beginning. Do NOT first write a standalone script and then convert it — this leads to mismatches between tested and saved code.

Based on the requirements, write a complete tool file following the format above. Key considerations:

- Choose a clear, descriptive function name using `snake_case`
- Write a comprehensive docstring
- Add proper error handling (try/except, input validation)
- Log inputs and outputs
- Keep it focused — one tool does one thing well
- If the tool needs web search or crawling, use `seekr_sdk` (available in both backend and sandbox)

### Step 3: Test the @tool in Sandbox

Test the actual `@tool` function (NOT a separate standalone script):

1. Save the tool to `{workspace_dir}/tools_dev/{tool_name}.py`
2. Write a test script `{workspace_dir}/tools_dev/test_{tool_name}.py`:
   ```python
   import sys
   sys.path.insert(0, "{workspace_dir}/tools_dev")
   from {tool_name} import {tool_name}

   # Test cases — this calls the SAME @tool function that will be saved
   result = {tool_name}.invoke({{"param1": "value1", "param2": 42}})
   print(f"Result: {result}")
   ```
3. Run the test in the sandbox and verify the output
4. If there are errors, fix `{workspace_dir}/tools_dev/{tool_name}.py` and re-test

**IMPORTANT**: The test MUST import and invoke the `@tool` function from `tools_dev/{tool_name}.py`. Neve