# Authoring tools for dynamic sub-agents

A tool is an ordinary top-level Python function. Its function name becomes the tool name, its type
hints define the input schema, and its docstring tells the agent when and how to call it.

## Basic structure

```python
def measure_accuracy(model_path: str, dataset: str = "validation") -> float:
    """Measure a saved model against a named dataset.

    Args:
        model_path: Path to the saved model.
        dataset: Dataset split to evaluate.

    Returns:
        Accuracy from zero to one.
    """
    return evaluate(model_path, dataset)
```

## Authoring guidelines

- Use specific type hints such as `list[str]` instead of `list` or `Any`.
- Give every parameter a clear description in the docstring.
- Describe the return value and its units or valid range.
- Use defaults only when the default is safe and unsurprising.
- Raise errors that explain what the agent can change before retrying.
- Keep each tool focused on one operation.
- Make repeated calls with the same inputs safe whenever possible.
- Return structured values when later tools need to inspect individual fields.

## Designing a useful tool set

Give the dynamic sub-agent the smallest set of operations needed to propose, measure, and preserve
a result. Keep the judge independent from the candidate-producing tools so a candidate cannot mark
itself as successful.