Tool design — the most important agent skill

An agent's quality is bounded by the quality of its tools. Each tool needs:

1. A clear name — search_docs, not search
2. A precise description — what it does, when to use it
3. A typed JSON schema for parameters
4. A deterministic implementation
5. Useful, structured outputs

A fuzzy tool ('do_stuff') confuses the LLM. A precise tool ('lookup_customer_by_email') guides it. Spend more time on tool design than agent prompting. ROI is higher.

When a tool fails, return a STRUCTURED error to the model. Not a Python traceback.

Good: { 'error': 'NOT_FOUND', 'detail': 'No customer with email x@y.com', 'suggestions': ['try search_customer_by_phone'] }

Bad: 'Traceback (most recent call last)... KeyError: ...'

The model can read the structured error and pivot — try a different tool, ask for clarification. The traceback just confuses it.

Your tools' error messages are part of your system prompt. Treat them with the same care.

JSON schema with rich descriptions, an enum for fixed-set parameters, and structured error returns. Read the description like you're an LLM seeing it cold.

Before plugging tools into an agent, unit-test them like any other function.

- Happy path returns expected shape
- Bad inputs return structured errors
- No state leaks between calls
- Latency p99 is acceptable

A flaky tool with the LLM-in-the-loop becomes a debugging nightmare. Test in isolation. Trust the agent only with tools that are themselves trusted.

Day 72 done.

- Tools = name + schema + behaviour
- Structured errors over tracebacks
- Rich descriptions, enums for sets
- Unit-test without the LLM

Tomorrow (Day 73): planning agents. Multi-step decomposition before execution.