Context Type 5-6: Tools and Tool Results

The previous two subtopics covered how the agent should BEHAVE (Instructions, Examples) and what it KNOWS (Knowledge, Memory). The final two context types in this course's taxonomy are about what the agent can DO in the world, and how it learns from having done it.

Type 5, Tools, extends the agent's power beyond language and takes real-world action. Each tool has parameters, inputs, and examples. The design here decides how well your agent uses external APIs. This is the layer that connects directly to this curriculum's agent-tool-use-implementation and MCP topics — Tools context is specifically the DESCRIPTION of what actions are available (their names, what parameters they take, example usage), which the agent reads to decide WHICH tool to call and HOW to call it correctly. This course's framing 'the design here decides how well your agent uses external APIs' echoes a real, recurring lesson from this curriculum's mcp-use-agents-and-clients topic: poorly described or too-numerous tools cause tool-name hallucination and confusion, so how Tools context is written matters as much as which tools exist.

Type 6, Tool Results, feeds the tool's results back to the model to enable self-correction, adaptation, and dynamic decision-making. This is a distinct context type from Tools itself — Tools is the MENU of available actions (known before any action is taken); Tool Results is the OUTCOME of actions actually taken (only known after). This distinction matters because it's exactly the Action/Observation loop from the agentic-ai-terms-glossary topic, given a formal place as its own context layer: an agent that calls a tool but never sees the result back in its context can't adapt its next decision based on what actually happened — Tool Results is what closes that loop, letting the agent notice a tool call failed, returned unexpected data, or partially succeeded, and adjust course accordingly.

This course states directly: these are the exact six layers that help you build fully context-aware Agents — Instructions, Examples, Knowledge, Memory, Tools, and Tool Results together. Each layer answers a different question an agent needs answered (who/why/how, what good looks like, what it knows generally, what it remembers specifically, what it can do, and what happened when it did) — and this course's claim is that missing any ONE of these six leaves a production agent structurally incomplete, regardless of how capable the underlying LLM is.

# Modeling Tools (the available-action MENU, known upfront) and
# Tool Results (the OUTCOME of an actual call, known only after) as
# two distinct context layers -- closing the action/observation loop.

TOOLS_CONTEXT = [
    {"name": "search_orders", "params": {"order_id": "str"},
     "example": "search_orders(order_id='A123') -> order status and details"},
    {"name": "issue_refund", "params": {"order_id": "str", "amount": "float"},
     "example": "issue_refund(order_id='A123', amount=29.99) -> confirmation"},
]

def render_tools_context(tools: list[dict]) -> str:
    """Context Type 5: the MENU of what's available, before any call."""
    lines = []
    for t in tools:
        lines.append(f"{t['name']}({t['params']}) -- e.g. {t['example']}")
    return "\n".join(lines)

def call_tool_and_get_result(tool_name: str, **kwargs) -> dict:
    """Stand-in for actually invoking a tool."""
    if tool_name == "search_orders":
        return {"order_id": kwargs["order_id"], "status": "delivered", "amount": 29.99}
    return {"error": "unknown tool"}

def render_tool_result_context(result: dict) -> str:
    """Context Type 6: fed back AFTER the call, enabling self-correction."""
    return f"Tool result: {result}"

print("=== Tools (Type 5) ===")
print(render_tools_context(TOOLS_CONTEXT))

result = call_tool_and_get_result("search_orders", order_id="A123")
print("\n=== Tool Results (Type 6) ===")
print(render_tool_result_context(result))
# The agent's NEXT decision (e.g. whether to call issue_refund) is
# informed by this Tool Result context, not just the original Tools menu