Example: Adding a Calculator to Our Agent › Common Pitfalls and Solutions

As you build your own tools, watch out for these common issues:

Pitfall: Tool descriptions are too vague

❌ Bad: "description": "Does math stuff"

✅ Good: "description": "Perform precise mathematical calculations including addition, subtraction, multiplication, division, and exponentiation"

The agent uses the description to decide when to use the tool. Be specific.

Pitfall: Parameter examples are missing

❌ Bad: "expression": {"type": "string", "description": "A math expression"}

✅ Good: "expression": {"type": "string", "description": "Math expression using +, -, *, /, **. Examples: '1234 * 5678', '100 + 50 - 25'"}

Examples help the agent format inputs correctly.

Pitfall: Error handling is missing

❌ Bad: Let exceptions crash the program

✅ Good: Catch exceptions and return structured error information

The agent can work with error messages. It can't work with crashes.

Pitfall: Outputs are unstructured

❌ Bad: return "The answer is 42"

✅ Good: return {"success": True, "result": 42}

Structured outputs give the agent flexibility in how it presents information.