Tool Call Optimization: Reducing the 'Syntax Tax'

"Tool Calling" (Function Calling) is the bridge between an LLM and the real world. However, every tool you provide to an LLM incurs a Synthetic Tax.

To use a tool, the model needs:

1. The Description: A detailed JSON schema for the function.
2. The JSON Output: A structured generation of parameters.
3. The Observation: An injection of the result back into the prompt.

In complex agents with dozens of tools, this "Bridging Language" can account for 40% of your total token spend. In this lesson, we learn how to Prune your Schemas, implement Manual Tool Selection, and use Compressed Response Formats to keep the syntax lean.

---

1. The Schema Weight

A standard JSON schema for a "Calculate Tax" tool might look like this:

{
  "name": "calc_tax",
  "description": "Calculates the tax for a specific state and income level",
  "parameters": {
    "type": "object",
    "properties": {
      "state_code": {"type": "string", "description": "The two-letter code..."},
      "income": {"type": "number", "description": "The annual gross..."}
    }
  }
}

Weight: 150 Tokens. If you send this with every turn, and you have 20 such tools, you are paying for 3,000 tokens of documentation on every request.

---

2. Technique 1: Schema Pruning

LLMs are smarter than we'll admit. They don't need verbose "Descriptions" for simple fields.

Inefficient: "state_code": {"description": "The two-letter US state code in uppercase like CA or NY"} Efficient: "s": {"type": "string"}

By using Micro-Keys (like s for state_code and i for income) and removing redundant descriptions, you can reduce schema size by 60%.

---

3. Technique 2: "Manual" Tool Calling (Prompt-Based)

Instead of using the provider's "Native Function Calling" feature (which usually force-injects the schema in a heavy way), you can use a Text-Only Prompt.

The Pattern:

"Available Tools: [search, calculate, email]. To call a tool, output: CALL name."

Token ROI: A text-based tool list is often 5x to 10x smaller than a structured JSON Schema array. For simple agents, "Prompt-Based Calling" is the ultimate token saver.

---

4. Technique 3: Compressed Tool Observations

When a tool returns data (e.g. a SQL query result), do not send the whole JSON object back to the model.

Bad (150 tokens): [{"id": 1, "name": "John", "role": "Admin", "last_login": "2024-01-01", "email": "john@corp.com"}]

Good (15 tokens): CSV: 1,John,Admin

The Rule: If the agent only asked for the "Name and Role," your Python backend should filter the tool's result before it hits the LLM's context.

---

5. Implementation: The Schema Minifier (Python)

Python Code: Stripping Tool Descriptions

def minify_tool_schema(schema: dict):
    """
    Remove docstrings and verbose types from a Pydantic 
    or JSON schema to save tokens.
    """
    minified = {
        "n": schema["name"],
        "p": {}
    }
    for k, v in schema["parameters"]["properties"].items():
        # We only keep the key and the type, removing 'description'
        minified["p"][k] = {"t": v["type"]}
        
    return minified

# Result: 
# Original: 150 tokens
# Minified: 40 tokens

---

6. Real-World Speed Gains

By reducing tool syntax, you reduce the Output Token Generation time. Generating a massive JSON block with 5 correctly nested keys takes much longer than generating a compact CALL calc(CA, 50000) string.

---

7. Summary and Key Takeaways

1. Descriptions are Optional: If the function name is obvious (get_weather), delete the description.
2. Key Minification: Use short keys for parameters (i vs income).
3. Filter Observations: Only return the data the agent actually needs to see.
4. Text-Based Pattern: For high-volume agents, use a simple text string for tool calls instead of heavy JSON schemas.

In the next lesson, The 'Planning' Step: Cost vs. Performance, we look at چگونه to manage the most expensive turn in the agentic loop.

---

Exercise: The Schema Audit

1. Find a tool in your codebase that has a nested JSON schema.
2. Calculate its current Token Weight using tiktoken.
3. Rewrite it manually using the "Micro-Key" technique.
4. Verify: Ask an LLM to call the minified tool.

• Does it still provide the right arguments? (Usually, Yes).
• Calculation: How many dollars would you save per 1 million calls with this change?

---

Congratulations on completing Module 9 Lesson 3! You are now a toolcall optimizer.