Module 4: Tool Design and Integration

Lesson 2: When to Expose Tools vs Embed Logic

As an architect, you face a recurring choice for every feature: Do I give Claude a Tool to do this, or do I just do it in code and send Claude the result?

This is the "Autonomy vs. Pre-processing" trade-off. Choosing wrong leads to high latency, high cost, and "Hallucinated Loops." In this lesson, we establish the Decision Rubric for tool exposure.

---

1. Option A: Embedding Logic (Pre-processing)

In this model, the system executes logic before or after the LLM call. The LLM never "sees" the tool; it only sees the end result.

Example:

Instead of giving Claude a get_user_location tool, you fetch the user's location using standard browser APIs and include it in the System Prompt: "The user is currently in London, UK."

Use Case:

• Data that is Always Required.
• Data that is Static for the duration of the conversation.
• High-latency data that you want to parallelize with the initial model prompt.

---

2. Option B: Exposing Tools (Lazy Loading)

In this model, you define the tool and give it to Claude. The system only executes the logic if and when Claude asks for it.

Example:

You give Claude a run_bank_transaction tool with parameters for amount and recipient.

Use Case:

• Data that is Optional. (The user might not ask for it).
• Expensive operations (Don't run them unless needed).
• Interactive workflows where the model must choose specific parameters based on conversation flow.

---

3. The "Tool vs. Fact" Decision Matrix

Choose EMBEDDED LOGIC if...	Choose EXPOSED TOOL if...
The data is needed for 100% of queries.	The data is needed for < 30% of queries.
The logic is simple and fast (< 100ms).	The logic is complex or slow (> 500ms).
The logic has only one outcome.	the logic requires model judgment (e.g., search).
You want to save one "Turn" of latency.	You want the agent to be "Autonomous".

---

4. Architectural Trap: "The Bloated System Prompt"

A common mistake is embedding too much data because you want to save a "Tool Turn."

• If you embed a 50-page documentation file instead of giving Claude a search_docs tool, you are wasting 30,000 tokens per interaction.
• The Rule of 500: If the data you are embedding is > 500 tokens and isn't needed for every turn, Turn it into a Tool.

---

5. Summary

• Embed logic for global context and speed.
• Expose tools for specific capabilities and cost-efficiency.
• An architect minimizes the system prompt by delegating "Heavier" work to the tool layer.

In the next lesson, we will look at how to actually build these interfaces: Tool Interface Design Principles.

---

Interactive Quiz

1. Why would you embed a user's role (e.g., "Admin") in the prompt rather than giving a get_user_role tool?
2. What is the "Rule of 500" for context management?
3. How does exposing a tool increase the "Latency" of the final answer?
4. Scenario: Your agent needs to translate text. Should you use a tool (translate_text) or just ask Claude to translate it directly in the chat? Why?

---

Reference Video: