Tool Calling Educational Project

An educational project to understand how function calling and tool calling work in language models, from low-level implementations to modern native support.

🎯 Objective

This project explores two approaches for language models to "call functions":

1. Pseudo Tool Calling: Simulating tool calling in models without native support
2. Real Tool Calling: Using native support from modern models

📚 What you'll learn

• How tool calling works "under the hood"
• Differences between structured JSON Schema vs native tool calling
• Limitations of older models vs modern capabilities
• How to process and execute function calls manually
• Best practices for validation and error handling

🔬 Approaches Explored

1. Pseudo Tool Calling (pseudo_tool_calling.py)

Model: llama2 (without native tool calling support)

Method:

• ✨ JSON Schema to force structured output
• 🎯 Detailed system prompt explaining expected format
• 🔧 Manual parsing of JSON result
• ⚡ Manual function execution

# Approach: Structured Output
response = chat(
    model='llama2',
    messages=messages,
    format=tools_schema,  # JSON Schema
)

# Manual parsing
result = json.loads(response.message.content)

Advantages:

• 📖 You understand exactly how it works
• 🛠️ Total control over the process
• 🔧 Works with any model
• 🎓 Educational for understanding fundamentals

Limitations:

• 📝 Complex system prompts
• 🐛 Limited JSON Schema in older models
• ⚠️ No format guarantees
• 🔄 More manual code

2. Real Tool Calling (real_tool_calling.py)

Model: llama3.2 (with native tool calling support)

Method:

• 🚀 Standard tool definitions (OpenAI format)
• 💬 Simple system prompt
• 🤖 Model decides when and how to use tools
• ⚡ Native tool calls in response

# Approach: Native Tool Calling
response = chat(
    model='llama3.2',
    messages=messages,
    tools=tools,  # Native definitions
    # No need for temperature=0 with native tool calling
)

# Native tool calls
if response.message.tool_calls:
    # Process tool_calls directly

Advantages:

• 🎯 More reliable and accurate
• 📝 Simpler prompts
• 🔧 Better integration
• 🚀 Advanced features

Limitations:

• 📦 Requires modern models
• 🎛️ Less granular control
• 🔒 Depends on model implementation

🛠️ Implemented Functions

Both approaches implement the same basic functions:

def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

📋 Test Cases

The scripts include tests covering:

Simple Operations

• "Multiply 2 by 3"
• "Add 15 and 25"

Multiple Independent Operations

• "Multiply 4 by 5 and add 6 to 7"
• "Calculate 8*9 and also 10+15"
• "I need both 3*6 and 12+8"
• "Find 7*8 and 20+25"

Note: Examples focus on independent operations, not sequential ones, to avoid dependency problems between results.

🔄 Processing Flow

Both approaches follow the same general flow:

User Request → Model Processing → Tool Calls → Function Execution → Natural Response

Pseudo Tool Calling Flow:

"Multiply 2 by 3" 
→ llama2 + JSON Schema 
→ {"tool_calls": [{"name": "multiply", "arguments": {"a": 2, "b": 3}}]}
→ Manual parsing + execution
→ "The result of multiplying 2 by 3 is 6."

Real Tool Calling Flow:

"Multiply 2 by 3"
→ llama3.2 + tools definition
→ response.message.tool_calls[0].function.name = "multiply"
→ Native tool call processing + execution  
→ "The result of multiplying 2 by 3 is 6."

📦 Requirements

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Install required models
ollama pull llama2      # For pseudo tool calling
ollama pull llama3.2    # For real tool calling

# Install Python dependencies
pip install ollama

🚀 How to Use

1. Pseudo Tool Calling

python3 pseudo_tool_calling.py

2. Real Tool Calling

python3 real_tool_calling.py

Both scripts run the same tests automatically and show the complete process.

🧠 Key Concepts Learned

JSON Schema vs Tool Definitions

# Pseudo (JSON Schema)
tools_schema = {
    "type": "object",
    "properties": {
        "tool_calls": {
            "type": "array",
            "items": {...}
        }
    }
}

# Real (OpenAI format)
tools = [{
    "type": "function",
    "function": {
        "name": "multiply",
        "description": "Multiply two numbers",
        "parameters": {...}
    }
}]

Validation and Error Handling

Pseudo Tool Calling:

• Manual validation of function names
• Defensive JSON parsing
• Handling of unrespected schemas

Real Tool Calling:

• Type conversion (strings → integers)
• Handling different argument formats
• Native tool_calls validation

Important Limitations

Sequential Operations: Neither approach handles well "What is 2*3 plus 4?" because it requires using the result of one function as input to another.

Workaround: Use independent operations like "Calculate 2*3 and 4+5".

🤔 Reflections

When to use each approach?

Pseudo Tool Calling:

• 📚 Educational projects
• 🔧 Maximum process control
• 📦 Models without native support
• 🎯 Simple and controlled cases

Real Tool Calling:

• 🚀 Production applications
• 🎯 Better user experience
• 📦 When you have modern models
• 🔧 Advanced features

Lessons Learned

1. Fundamentals matter: Understanding pseudo tool calling helps better use the real one
2. JSON Schema has limitations: Old models don't always respect advanced constraints
3. Validation is key: Always validate and handle errors, regardless of approach
4. Simplicity: Simple independent cases work better than complex operations

🔗 Additional Resources

• Ollama Documentation
• OpenAI Function Calling Guide
• JSON Schema Specification

👨‍💻 Author

• Name: Juanje Ojeda
• Email: [email protected]

🤖 AI Tools Disclaimer

This project was developed with the assistance of artificial intelligence tools:

Tools used:

• Cursor: Code editor with AI capabilities
• Claude-4-Sonnet: Anthropic's language model

Division of responsibilities:

AI (Cursor + Claude-4-Sonnet):

• 🔧 Initial code prototyping
• 📝 Generation of examples and test cases
• 🐛 Assistance in debugging and error resolution
• 📚 Documentation and comments writing
• 💡 Technical implementation suggestions

Human (Juanje Ojeda):

• 🎯 Specification of objectives and requirements
• 🔍 Critical review of code and documentation
• 💬 Iterative feedback and solution refinement
• 📋 Definition of project's educational structure
• ✅ Final validation of concepts and approaches

Collaboration philosophy: AI tools served as a highly capable technical assistant, while all design decisions, educational objectives, and project directions were defined and validated by the human.

---

This project is an educational exploration of function calling in LLMs, from fundamentals to modern implementations.