DEV Community: Nikita Kothari

Comprehensive Guide to System Design for Reliable Agentic Tool-Use with Claude

Nikita Kothari — Wed, 10 Jun 2026 17:59:45 +0000

Introduction: Building True Agentic AI

While large language models like Claude 3.5 Sonnet demonstrate exceptional deep reasoning capabilities, elegant code suggestions, and complex architectural understanding, they remain isolated without a bridge to the physical world. Without explicit tool integration, an LLM is a brilliant brain trapped in a jar—unable to audit local repositories, query active databases, or connect to external infrastructure. To transition from basic prompt engineering to true Agentic AI, developers must design production-grade systems that allow models to safely, reliably, and autonomously interact with external codebases and services using structured tool-use (function calling).

The Anatomy of an Agentic Skill

When providing an LLM with a tool, the system does not transmit raw executable binaries or Python code directly over the API. Instead, it provides a structured description—a blueprint—of what the system components can do. The model analyzes this specification, determines the appropriate tools and parameters needed based on user intent, and returns a structured request. The underlying application infrastructure then executes the requested function locally or externally, feeding the output back to the model to close the processing loop.
Every resilient agentic skill relies on three core design components:

The JSON Schema: The rigid technical blueprint that defines the tool's namespace, explicit execution purpose, and mandatory parameter data types. This structure allows the model to map conversational text to programmatic data structures without syntax degradation.
Explanatory Docstrings: While the schema dictates types and structures, semantic clarity inside the documentation strings instructs the model on the why and when of tool invocation, reducing false-positive execution triggers.
Defensive Error Handlers: External environments, file paths, and network networks are unpredictable. Tools must encapsulate executions inside local exception blocks, translating systemic crashes into descriptive, semantic text strings that the model can interpret to attempt self-correction.

State Orchestrator Loop Architecture

Relying purely on raw API outputs without operational layers creates fragile agent applications prone to runtime crashes, infinite execution loops, or argument hallucinations. A resilient agent architecture relies on a structured State Orchestrator Loop capable of managing the lifecycle of an autonomous workflow through three distinct operational phases:

Implementation: Reference Implementation Block
The Python implementation below establishes a functional, production-ready single-agent execution loop using the Anthropic API client. The codebase defines a local directory regex-scanning utility tool, registers its declarative schema with Claude, executes the intent safely within defensive try-except containers, and returns runtime outputs to the model for downstream contextual processing.

import os
import json
import re
from anthropic import Anthropic

#Initialize the Anthropic client


client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# 1. Define the actual Python function (The Skill)

def scan_directory_for_pattern(directory_path: str, pattern: str) -> str:
    """
    Scans files in a local directory to find matches for a regex pattern.
    """
    if not os.path.exists(directory_path):
        return f"Error: The directory '{directory_path}' does not exist."

    matches = []
    try:
        compiled_regex = re.compile(pattern)
        for root, _, files in os.walk(directory_path):
            for file in files:
                if file.endswith(('.py', '.js', '.json', '.txt', '.md', '.yml')):
                    file_path = os.path.join(root, file)
                    with open(file_path, 'r', errors='ignore') as f:
                        for line_num, line in enumerate(f, 1):
                            if compiled_regex.search(line):
                                matches.append(f"{file}: Line {line_num} -> {line.strip()}")

        if not matches:
            return "Scan complete. No matching patterns found."
        return "\n".join(matches[:20]) # Limit output size for context windows

    except Exception as e:
        return f"Execution Error: Failed to complete scan due to: {str(e)}"

# 2. Define the structural schema Claude expects
TOOL_DEFINITIONS = [
    {
        "name": "scan_directory_for_pattern",
        "description": "Searches through code and text files within a local directory for a specific regex pattern. Useful for auditing codebases, finding hardcoded keys, or searching for specific implementations.",
        "input_schema": {
            "type": "object",
            "properties": {
                "directory_path": {
                    "type": "string",
                    "description": "The absolute or relative path to the local directory to scan."
                },
                "pattern": {
                    "type": "string",
                    "description": "The regular expression pattern to look for (e.g., 'API_KEY =', 'TODO:')."
                }
            },
            "required": ["directory_path", "pattern"]
        }
    }
]

def run_agentic_loop(user_prompt: str):
    print(f"User: {user_prompt}\n")
    messages = [{"role": "user", "content": user_prompt}]

    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2000,
        tools=TOOL_DEFINITIONS,
        messages=messages
    )

    messages.append({"role": "assistant", "content": response.content})
    tool_calls = [block for block in response.content if block.type == "tool_use"]

    if tool_calls:
        for tool_call in tool_calls:
            tool_name = tool_call.name
            tool_args = tool_call.input
            tool_id = tool_call.id

            print(f"[Claude Intent] Wants to run tool '{tool_name}'")

            if tool_name == "scan_directory_for_pattern":
                try:
                    path = tool_args.get("directory_path")
                    pat = tool_args.get("pattern")
                    if not path or not pat:
                        tool_result = "Error: Missing required arguments."
                    else:
                        tool_result = scan_directory_for_pattern(path, pat)
                except Exception as e:
                    tool_result = f"System Schema Validation Error: {str(e)}"
            else:
                tool_result = f"Error: Tool '{tool_name}' is not supported."

            messages.append({
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_id,
                        "content": tool_result
                    }
                ]
            })

        final_response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2000,
            tools=TOOL_DEFINITIONS,
            messages=messages
        )
        print(f"Claude: {final_response.content[0].text}")
    else:
        print(f"Claude: {response.content[0].text}")

Scaling the Architecture for Parallel Tool Execution

To scale workloads, enterprise agents must often run multiple tools concurrently rather than sequentially. When Claude identifies that independent tasks can be addressed simultaneously, it issues an array containing multiple tool-use validation blocks inside a single transactional turn. Developers can optimize performance constraints by leveraging Python's native concurrent.futures.ThreadPoolExecutor module to run these operations inside independent worker threads.
from concurrent.futures import ThreadPoolExecutor, as_completed

def execute_single_tool(tool_name: str, tool_args: dict) -> str:
    try:
        if tool_name == "scan_directory_for_pattern":
            return scan_directory_for_pattern(tool_args.get("directory_path"), tool_args.get("pattern"))
        elif tool_name == "fetch_git_metadata":
            return f"Git Metadata: Active branch is 'main'."
        else:
            return f"Error: Tool '{tool_name}' not recognized."
    except Exception as e:
        return f"Execution Error on {tool_name}: {str(e)}"

def run_parallel_agentic_loop(user_prompt: str):
    messages = [{"role": "user", "content": user_prompt}]

    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2000,
        tools=[...], 
        messages=messages
    )

    messages.append({"role": "assistant", "content": response.content})
    tool_calls = [block for block in response.content if block.type == "tool_use"]

    if tool_calls:
        tool_results_payload = []

        # Deploy concurrent thread pool workers for parallel dispatch
        with ThreadPoolExecutor(max_workers=len(tool_calls)) as executor:
            future_to_tool = {
                executor.submit(execute_single_tool, tool.name, tool.input): tool 
                for tool in tool_calls
            }

            for future in as_completed(future_to_tool):
                tool_call_object = future_to_tool[future]
                try:
                    result_string = future.result()
                except Exception as exc:
                    result_string = f"Thread collapsed: {exc}"

                tool_results_payload.append({
                    "type": "tool_result",
                    "tool_use_id": tool_call_object.id,
                    "content": result_string
                })

        # Batch collect all completed results back to the runtime execution sequence
        messages.append({
            "role": "user",
            "content": tool_results_payload
        })

        final_response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2000,
            messages=messages
        )
        print(f"Claude: {final_response.content[0].text}")

Production System Constraints and Guardrails

Deploying autonomous tool-use frameworks into production multi-user ecosystems introduces severe scaling bottlenecks and security vulnerabilities if left unmanaged. System designers must enforce three foundational production controls:

The Principle of Least Privilege: Tools must remain highly restricted in scope. Broad terminal tools (e.g., executing shell commands) introduce significant injection risks. Architect specific, single-purpose functions instead, ensuring that any malicious runtime manipulation is strictly contained by the limited environment boundary of the structural definition.
Thread Safety and State Management: Read-only operations can execute concurrently across standard threads. However, if multiple concurrent tool calls attempt to alter or write to shared system states, resources, or databases, developers must implement synchronization wrappers such as threading.Lock() to prevent race conditions or data corruption.
Token Management and Response Aggregation: Returning vast, unprocessed payloads (e.g., massive log histories or multi-row SQL tables) to the LLM will inflate token consumption and increase context-window overhead costs. Middleware abstraction layers must truncate, aggregate, or slice tool output blocks down to critical information before returning payloads to the agent loop.

From Coder to Architect: How I Rebuilt My Workflow Using Claude and MCP

Nikita Kothari — Mon, 11 May 2026 05:21:31 +0000

The "AI anxiety" felt by many developers often stems from the fear that the act of creation is being taken away. But clinging to the manual labor of syntax means missing out on the opportunity to become a true system architect. By treating AI integration not as a shortcut, but as an exercise in Engineering Efficiency and Data-Driven Self-Reflection, we can fundamentally rewire how we work.

Here is how transitioning from a traditional developer to an AI-augmented engineer can elevate your data science and engineering workflows.

The Paradigm Shift: Claude 101 and the Discovery of MCP

My journey began with a "day zero" deep dive. I stopped trying to use Claude as a glorified Google Search and started treating it as an operating system. The most significant turning point was mastering the Model Context Protocol (MCP).

For the uninitiated, MCP is an open standard that enables AI models to securely interact with local and remote data sources. Instead of copy-pasting code into a chat window, MCP allows Claude to "see" your file system, your GitHub repositories, and even your Slack channels directly.

By setting up MCP connectors, I bridged the gap between a static LLM and a living environment. I wasn't just talking to an AI; I was building a command center that had the context of my entire professional life.

References

https://modelcontextprotocol.io/introduction

The "Secondary Brain" Framework

In my 30s, I’ve realized that cognitive load is the silent killer of productivity. I adopted a "Secondary Brain" philosophy — a concept popularized by Tiago Forte — but with an AI twist.

I treated Claude as my Secondary Brain, responsible for execution and information retrieval, which allowed my Primary Brain to focus on strategy and problem-solving. This created a fascinating feedback loop:

The Challenge: I would use the Secondary Brain to draft logic.
The Critique: My Primary Brain would challenge that logic, looking for edge cases.
The Refinement: We would iterate.

This partnership didn't take away my love for coding; it elevated it. I was no longer fighting with semicolons; I was debating system architecture with a partner that never gets tired.

References

https://www.buildingasecondbrain.com/

Practical Automation: The 5-Minute Wins

The real power of an AI agent is revealed in the "boring" tasks. I analyzed my day to find where I was losing time to "mechanical sympathy" — the friction of using tools.

1. Automating the Git Workflow

The real power of an AI agent lies in eliminating the friction of "mechanical sympathy", the time lost to the mechanics of using tools. For example, the traditional Git workflow can be a significant cognitive drain. By building a custom Claude Skill, a 5-to-7 minute context switch can be reduced to 30 seconds.

Here is an example prompt structure you can use to automate your Git workflow based on the process outlined in the sources:

Context: I have just finished working on [describe task/changes].

Action Required:

1. Generate a branch name based on the task.
2. Draft a commit message following our team's semantic versioning.
3. Link the Jira/Azure DevOps work item for this task.
4. Execute the push.

Similarly, you can scaffold Test-Driven Development (TDD) at scale. By providing functional requirements to the AI, it can generate failing test cases first, enforcing high code quality and bypassing the "blank page" syndrome. These custom AI skills can then be scaled across a team via standardized prompts and JSON schemas to build a shared AI-augmented infrastructure.

2. Test-Driven Development (TDD) at Scale

Writing tests is often the first thing skipped under pressure. By using Claude to "scaffold" my TDD process, I provide the functional requirements, and it generates the failing test cases first.

This forces me to maintain high code quality without the "blank page" syndrome that usually accompanies writing unit tests.

Mentorship and Scaling the Team

Productivity is a "force multiplier" only if it’s shared. Once I mastered these skills, I reached out to my peers for mentorship. We started sharing "Claude Skills" — standardized prompts and JSON schemas — within our team.

This created a rising tide that lifted all boats. We moved from a group of individuals struggling with tickets to a unified team that utilized a shared AI-augmented infrastructure.

For those looking to implement this, I highly recommend exploring Anthropic’s Tool Use documentation to understand how to build your own custom agents.

References

https://docs.anthropic.com/en/docs/build-with-claude/tool-use

The Friday Reflection: The Pro-Tip for Growth

For data science and engineering professionals, Data-Driven Self-Reflection is the ultimate tool for continuous improvement. The most impactful ritual you can adopt is the "Friday Reflection".

Every Friday, use your MCP connectors to allow the AI to scan your completed work items, Git commits, and Slack messages for the week.

You can prompt the AI with the following:

Analyze my Slack messages, Git commits, and completed work items for this week. Based on this data, answer the following:

1. What was the overarching "theme" of my week (e.g., was I stuck in meetings or actively building)?

2. Where were the workflow bottlenecks?

3. Based on my output, what should my top priorities be on Monday to be 1% better?

This summary provides a level of data-backed self-awareness that is impossible to calculate manually, transforming a chaotic week into a structured, quantitative roadmap for professional growth.

References

https://www.google.com/search?q=https://docs.anthropic.com/en/docs/build-with-claude/tool-use

Closing Thoughts: Change is the Only Constant

If you are an engineer or data professional today, your value is no longer in your typing speed, but in how effectively you can direct the intelligence at your fingertips.

Take the time to learn MCP connectors, explore Anthropic’s Tool Use documentation, and build a system that measures and improves your efficiency.

By treating AI as your data-driven secondary brain, you will not just work faster — you will work fundamentally better.

Key Resources for Your Journey

Model Context Protocol (MCP) Official Site — Learn how to connect Claude to your data.
- https://modelcontextprotocol.io/
The 12-Factor App Methodology — A great reminder of the architectural principles your AI agents should follow.
- https://12factor.net/
Anthropic’s Prompt Engineering Guide — To turn your "Claude 101" into "Claude Expert."
- https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview