Overview

Chapter 5: Agentic Prompts & Tool Orchestration

Playbook: PB-01 (Prompt Engineering Playbook)
Target Audience: Year 1 Computer Science & Software Engineering Students
Prerequisites: Chapter 1: LLM Foundations, Chapter 2: Core Prompting Architectures, Chapter 3: System Prompts, Chapter 4: Reasoning Paradigms, Python 3.11+
Steering Reference: `instruction.md`

5.1 The Big Picture & Real-World Analogy

The Master Chef and the Smart Kitchen

Imagine a world-renowned master chef. The chef's mind contains encyclopedic knowledge: thousands of recipes, flavor harmonies, and culinary science (this is like the Large Language Model's vast pre-trained weights).

However, the chef has no physical hands in this kitchen! Instead, the chef stands in front of a voice-activated robotic workstation with precision appliances:

• A robotic knife that slices vegetables to exact millimeter widths.
• An electric convection oven that bakes at exact temperatures.
• A digital scale and timer.

The chef cannot bake a souffle just by thinking about it. If the chef wants to bake, they must speak a precise, unambiguous command:

call:convection_oven(temperature_c=180, duration_minutes=25, mode="gentle")

The robotic oven (the Tool Dispatcher) receives this command, executes the physical baking, and reports back:

observation: "Baking completed successfully. Internal core temperature reached 85°C."

The chef hears this observation, thinks about the next step, and announces:

call:plate_dessert(garnish="powdered_sugar", plate_id="porcelain_white")

This is exactly how Agentic AI and Tool Calling work!

1. The neural network never connects directly to a database, calculates math on raw silicon, or runs terminal commands inside its weights.
2. The model simply emits structured text (JSON or XML) requesting an external tool.
3. Your Python program (the client runtime) intercepts the text, calls the real API or database, and feeds the resulting output back to the model as an observation.

5.2 Engineering Jargon Demystifier Table

5.3 The 5-Minute Micro-Lab: The Micro Tool Dispatcher

Run this zero-dependency Python script to see how a model's structured tool request is intercepted, executed in Python, and synthesized into a final answer:

"""
Micro-Lab: 20-Line Deterministic Tool Dispatcher
PB-01 Chapter 5 Micro-Lab (Zero External Dependencies)
"""
import json

# 1. Define actual Python tool functions
def tool_add(a: int, b: int) -> int:
    return a + b

def tool_multiply(a: int, b: int) -> int:
    return a * b

TOOL_REGISTRY = {"add": tool_add, "multiply": tool_multiply}

# 2. Simulated LLM output: the model generated a JSON tool call instead of text
mock_model_output = '{"tool": "multiply", "args": {"a": 125, "b": 8}}'

# 3. Client-Side Dispatcher
def dispatch_tool_call(raw_json: str) -> str:
    payload = json.loads(raw_json)
    tool_name = payload["tool"]
    args = payload["args"]
    
    if tool_name not in TOOL_REGISTRY:
        return f"[ERROR] Unknown tool: {tool_name}"
    
    result = TOOL_REGISTRY[tool_name](**args)
    return f"[TOOL OBSERVATION] {tool_name}({args}) => Result: {result}"

if __name__ == "__main__":
    print("=== Simulated Model Generated Output ===")
    print(mock_model_output)
    print("\n=== Client-Side Dispatcher Execution ===")
    observation = dispatch_tool_call(mock_model_output)
    print(observation)
    print("\n=== Synthesized Final Answer ===")
    print(f"The product of 125 and 8 is 1000.")

5.4 How It Works Under the Hood

1. The Tool Execution Loop

       User Request [x] ──> [ Transformer Forward Pass ]
                                      │
                                      ▼
                        Emits Special Delimiter Token
                  (e.g., `<|tool_call|>` or `call:tool_name{...}`)
                                      │
                                      ▼
                      [ Client-Side Tool Dispatcher ]
                                      │
                     ┌────────────────┴────────────────┐
                     ▼                                 ▼
             [ JSON Validation ]              [ Sandboxed Execution ]
             (Schema Conformance)             (API, DB, Shell, Code)
                     │                                 │
                     └────────────────┬────────────────┘
                                      │
                                      ▼
                          Raw Execution Observation
                                      │
                                      ▼
               Appended to Context: `<|tool_response|>`
                                      │
                                      ▼
                        [ Model Synthesizes Answer ]

2. Schema Injection & Provider Differences

When you configure tools in an API request, the provider injects the tool descriptions into the model's system context. Notice an important provider syntax difference:

• OpenAI & Google Gemini: Expect a top-level key named "parameters" containing the JSON schema:

  {"type": "function", "function": {"name": "query_db", "parameters": {...}}}
  

• Anthropic Claude: Expects the key named "input_schema":

  {"name": "query_db", "description": "...", "input_schema": {...}}
  

[!IMPORTANT] If you send "parameters" to Anthropic's Messages API instead of "input_schema", the tool is silently ignored, and Claude will not know the tool exists!

3. Engineering High-Recall Tool Descriptions

When an agent has access to 15 different tools, how does it pick the right one? The self-attention heads evaluate semantic similarity between the user's prompt and the tool descriptions.

1. Explicit Negative Demarcation:
   • Bad: "Fetches user records."
   • Production: "Retrieves read-only customer account profile by user_id. Do NOT use for payment/credit card details; use 'get_billing_profile' for financial records."
2. Strict Type Demarcation: Specify units and formats directly in parameter descriptions ("ISO-8601 UTC timestamp string", "Integer epoch seconds").
3. Pervasive Defaults: Never force the model to provide unnecessary fields. If a parameter is optional, default it to None in your schema.

5.5 Freshman Survival Guide: 3 Traps to Avoid

Trap 1: Assuming the AI Runs the Code Internally

• The Mistake: Writing a prompt like "Execute 'rm -rf /tmp' on the server" and expecting the LLM itself to run the command on silicon.
• Why it fails: LLMs only generate text tokens. The model has zero access to your computer, file system, or network unless you write a Python script that takes that text and executes it.
• Fix: Treat the model as a text generator. Any tool execution must pass through strict permission checks and sandboxing in your Python dispatcher.

Trap 2: Infinite Error Loops Without Circuit Breakers

• The Mistake: Running while True: in an agentic loop where the agent keeps trying to call an API that is offline or returning HTTP 500.
• Why it fails: The model reads "Error: Connection Timed Out" and reasons: "Let me try again." It will run 500 times in 2 minutes, exhausting your budget.
• Fix: Always enforce a maximum step limit (e.g. MAX_STEPS = 5). If the tool fails twice with the same error, terminate and return an error report.

Trap 3: Semantic Collision in Tool Names

• The Mistake: Providing two tools named get_user_info and search_customer_profile without clear negative demarcation.
• Why it fails: The model cannot tell which tool to use, leading to stochastic, random tool selection.
• Fix: Merge redundant tools into one, or clearly demarcate their distinct purposes in the descriptions.

5.6 Production Contrast: Cloud Infrastructure Restart Tool

[FAIL] Naive Tool Schema & Prompt

{
  "name": "restart_service",
  "description": "Restarts a service in our cluster",
  "parameters": {
    "type": "object",
    "properties": {
      "service": {"type": "string"},
      "environment": {"type": "string"}
    }
  }
}

Prompt: "Restart the auth service now."
Why it fails: Environment is ambiguous (did the user mean staging, dev, or prod?); no idempotency checks; no approval confirmation token; high risk of catastrophic accidental production outage.

[PASS] Production-Grade Tool Schema with Safe Guardrails

{
  "name": "initiate_service_restart",
  "description": "Initiates a graceful rolling restart of an authorized microservice in the target cluster. DESTRUCTIVE ACTION: Requires explicit approval token for production environments. Do NOT use for configuration changes; use 'update_service_config' instead.",
  "parameters": {
    "type": "object",
    "required": ["cluster", "service_id", "rolling_restart", "approval_token"],
    "properties": {
      "cluster": {
        "type": "string",
        "enum": ["dev", "staging", "prod"],
        "description": "Target environment. If 'prod', approval_token must match security nonce."
      },
      "service_id": {
        "type": "string",
        "enum": ["auth-api", "billing-gateway", "data-ingest", "search-indexer"]
      },
      "rolling_restart": {
        "type": "boolean",
        "description": "True ensures zero downtime by restarting pods sequentially."
      },
      "approval_token": {
        "type": "string",
        "description": "Cryptographic or supervisor authorization token for production restarts."
      }
    }
  }
}

5.7 Production Code Lab: Resilient Tool Dispatcher with Auto-Correction Loop

Below is a complete, runnable Python 3.11+ module demonstrating an enterprise tool-calling dispatcher. It implements:

1. Declarative tool registry with type validation.
2. Simulated LLM tool calling with intentional malformed parameters.
3. Automated self-correction feedback loop (bounded at 2 attempts).
4. Safe execution and structured output formatting.

"""
Enterprise Agentic Tool Dispatcher with Bounded Self-Correction
Architecture: PB-01 Chapter 5 Production Lab
Dependencies: Python 3.11+ Standard Library (Zero external dependencies)
"""

from __future__ import annotations
import json
from dataclasses import dataclass
from typing import Dict, Any, Callable, Tuple, List, Optional


# ---------------------------------------------------------------------------
# 1. Tool Metadata & Registry
# ---------------------------------------------------------------------------

@dataclass
class ToolDefinition:
    name: str
    description: str
    parameter_schema: Dict[str, type]
    required_fields: List[str]
    is_destructive: bool
    executor: Callable[..., Dict[str, Any]]


class ToolRegistry:
    def __init__(self):
        self._tools: Dict[str, ToolDefinition] = {}

    def register(self, tool: ToolDefinition) -> None:
        self._tools[tool.name] = tool

    def get(self, name: str) -> Optional[ToolDefinition]:
        return self._tools.get(name)

    def validate_call(self, tool_name: str, arguments: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
        tool = self.get(tool_name)
        if not tool:
            return False, f"Unknown tool: '{tool_name}'"

        # Check required fields
        for field in tool.required_fields:
            if field not in arguments:
                return False, f"Missing required parameter: '{field}'"

        # Check parameter types
        for param, val in arguments.items():
            if param in tool.parameter_schema:
                expected_type = tool.parameter_schema[param]
                if not isinstance(val, expected_type):
                    return False, (
                        f"Type mismatch for parameter '{param}': "
                        f"Expected {expected_type.__name__}, got {type(val).__name__} ({repr(val)})"
                    )

        return True, None


# ---------------------------------------------------------------------------
# 2. Domain Tool Implementation
# ---------------------------------------------------------------------------

def restart_service_handler(cluster: str, service_id: str, replica_count: int) -> Dict[str, Any]:
    """Mock handler simulating infrastructure operation."""
    if cluster not in ["dev", "staging", "prod"]:
        raise ValueError(f"Invalid cluster target: {cluster}")
    return {
        "cluster": cluster,
        "service_id": service_id,
        "replica_count": replica_count,
        "action": "ROLLING_RESTART_INITIATED",
        "timestamp_utc": "2026-09-08T07:15:00Z"
    }


# ---------------------------------------------------------------------------
# 3. Agentic Runtime Dispatcher with Bounded Auto-Correction
# ---------------------------------------------------------------------------

class AgenticToolDispatcher:
    def __init__(self, registry: ToolRegistry, max_correction_attempts: int = 2):
        self.registry = registry
        self.max_correction_attempts = max_correction_attempts

    def execute_with_auto_correction(
        self,
        initial_raw_payload: str,
        llm_fix_generator: Callable[[str, str], str]
    ) -> Dict[str, Any]:
        """
        Attempts execution of a tool call payload. If schema validation fails,
        invokes bounded feedback correction loop.
        """
        current_payload = initial_raw_payload

        for attempt in range(self.max_correction_attempts + 1):
            try:
                parsed = json.loads(current_payload)
            except json.JSONDecodeError as exc:
                if attempt == self.max_correction_attempts:
                    return {"status": "FAILED", "error": f"JSONDecodeError: {str(exc)}", "attempts": attempt}
                feedback = f"Malformed JSON: {str(exc)}. Ensure strictly formatted RFC 8259 JSON."
                current_payload = llm_fix_generator(current_payload, feedback)
                continue

            tool_name = parsed.get("tool")
            args = parsed.get("parameters", {})

            is_valid, error_msg = self.registry.validate_call(tool_name, args)
            if is_valid:
                tool = self.registry.get(tool_name)
                assert tool is not None
                execution_result = tool.executor(**args)
                return {
                    "status": "SUCCESS",
                    "tool": tool_name,
                    "attempts_required": attempt,
                    "data": execution_result
                }
            else:
                if attempt == self.max_correction_attempts:
                    return {"status": "FAILED", "error": error_msg, "attempts": attempt}
                feedback = f"Schema Validation Error: {error_msg}. Rectify parameters and return fixed JSON."
                current_payload = llm_fix_generator(current_payload, feedback)

        return {"status": "FAILED", "error": "Max correction loops exceeded", "attempts": self.max_correction_attempts}


# ---------------------------------------------------------------------------
# 4. Executable Verification Harness
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    print("=== Chapter 5 Resilient Tool Dispatcher Lab ===")

    # Initialize registry
    registry = ToolRegistry()
    registry.register(
        ToolDefinition(
            name="restart_service",
            description="Executes a rolling restart of an authorized service.",
            parameter_schema={
                "cluster": str,
                "service_id": str,
                "replica_count": int
            },
            required_fields=["cluster", "service_id", "replica_count"],
            is_destructive=True,
            executor=restart_service_handler
        )
    )

    # 1. Simulating an initial buggy payload emitted by LLM (replica_count passed as string 'three')
    buggy_first_emission = json.dumps({
        "tool": "restart_service",
        "parameters": {
            "cluster": "prod",
            "service_id": "auth-api",
            "replica_count": "three"  # TYPE ERROR: Expected int, got str
        }
    })

    # 2. Simulated LLM repair function that fixes the error based on feedback
    def mock_llm_corrector(bad_payload: str, error_feedback: str) -> str:
        print(f"  [Dispatcher Feedback Triggered]: {error_feedback}")
        corrected = {
            "tool": "restart_service",
            "parameters": {
                "cluster": "prod",
                "service_id": "auth-api",
                "replica_count": 3  # Corrected to integer
            }
        }
        return json.dumps(corrected)

    dispatcher = AgenticToolDispatcher(registry=registry, max_correction_attempts=2)

    print("\nExecuting tool call with simulated self-correction...")
    outcome = dispatcher.execute_with_auto_correction(
        initial_raw_payload=buggy_first_emission,
        llm_fix_generator=mock_llm_corrector
    )

    print("\nExecution Outcome:")
    print(json.dumps(outcome, indent=2))

    assert outcome["status"] == "SUCCESS", "Dispatcher must recover from single type error"
    assert outcome["attempts_required"] == 1, "Should succeed on second attempt (attempt index 1)"
    assert outcome["data"]["replica_count"] == 3, "Fixed payload must pass integer replica_count"

    print("=== Verification Lab PASSED: Bounded Auto-Correction Loop Executed ===")

5.8 Architecture Trade-Off Matrix & Operational Failure Checklist

Engineering Trade-Off Matrix

The 10 Operational Failure Modes in Tool Orchestration

1. The Unbounded Auto-Correction Loop: Allowing an agent to repeatedly retry failed API calls indefinitely without setting max_attempts <= 2.
2. Missing Schema Invariants: Failing to declare required fields or enum constraints in schemas, resulting in missing parameters.
3. Provider Schema Misalignment: Sending OpenAI-formatted "parameters" keys to Anthropic's Claude API instead of "input_schema".
4. Tool Docstring Ambiguity: Writing vague 5-word docstrings without negative demarcation, causing the model to call the wrong tool.
5. Silent State Invalidation: Executing destructive tool actions without an approval gate or rollback mechanism.
6. Token Bloat via Oversized Schemas: Exposing 50+ detailed tool schemas simultaneously in one prompt, crowding out working context.
7. Type Coercion Traps: Expecting the model to always output native numeric types without checking for stringified numbers ("42" vs 42).
8. Neglecting Idempotency: Calling non-idempotent endpoints (e.g. credit card charging) in an agentic retry loop.
9. Observation Overload: Returning 5 megabytes of raw API telemetry directly into the context window, causing immediate context truncation.
10. Unchecked Shell / Code Execution: Allowing raw model outputs to execute directly in a root terminal without container sandboxing.