Fix AI Agent Tool-Calling Chaos with Prompt Engineering and MCP Protocol

Introduction

The author describes a common problem when building AI agents: the agent often calls the wrong tool, searches when it should not, or passes malformed parameters, resulting in a tool‑calling success rate of only around 30%.

1. Prompt Engineering as the Foundation

Prompt engineering is treated as the "operation manual" for the agent. A clear, well‑structured prompt dramatically improves tool‑calling accuracy. The author provides a ready‑to‑use prompt template that enforces three constraints:

When to call a tool : Only call a tool if the task truly requires external information.

Tool usage and parameter requirements : Explicitly list each tool, its purpose, and required parameters.

Output format : Use a strict JSON‑like syntax so the model’s output can be parsed reliably.

The template is shown in a pre block and includes rules such as "only one tool per call", "no fabricated parameters", and a concrete output format like

<|FunctionCallBegin|>[{"name":"tool","parameters":{"param":"value"}}]<|FunctionCallEnd|>

. Applying this template reduced the error rate by half.

2. Advanced Optimization with MCP Protocol

While prompt engineering solves many issues, it becomes cumbersome as the number of tools grows and when switching between large‑model providers. The Model Context Protocol (MCP) offers a standardized interface for tool calls, handling parsing and model‑specific differences automatically.

MCP Core Advantages

Standardized interface : All tools follow a common definition, eliminating long prompts.

Multi‑model compatibility : Works with OpenAI, Anthropic, Claude, 文心一言, etc., without code changes.

Security and control : Supports permission checks, parameter validation, and audit logging.

Rich ecosystem : Hundreds of ready‑made tools are available.

Spring Boot Integration (5‑minute demo)

Step 1 – Add the Maven dependency:

<dependency>
  <groupId>io.modelcontextprotocol</groupId>
  <artifactId>mcp-spring-boot-starter</artifactId>
  <version>0.2.0</version>
</dependency>

Step 2 – Define a tool with the @McpTool annotation:

import io.modelcontextprotocol.server.tool.McpTool;
import org.springframework.stereotype.Component;

@Component
public class SpringDocTools {
    /** Search Spring official documentation */
    @McpTool(
        name = "search_spring_doc",
        description = "Search Spring official docs for a specific version, e.g., 3.2.0",
        parameters = {
            @McpParameter(
                name = "version",
                description = "Spring version in x.y.z format",
                required = true,
                pattern = "\\d+\\.\\d+\\.\\d+"
            )
        }
    )
    public String searchSpringDoc(String version) {
        return "Spring Boot " + version + " New features:
1. Virtual threads
2. Observability enhancements
3. GraalVM native image optimizations";
    }

    /** Execute Java code */
    @McpTool(
        name = "execute_code",
        description = "Execute complete Java code with a main method",
        parameters = {
            @McpParameter(
                name = "code",
                description = "Full runnable Java code",
                required = true
            )
        }
    )
    public String executeCode(String code) {
        return "Code executed successfully, result: Hello World";
    }
}

Step 3 – Configure MCP in application.yml:

mcp:
  server:
    enabled: true
    tools:
      base-packages: com.example.agent.tools
    security:
      enabled: true
    allowed-tools:
      - search_spring_doc
      - execute_code

Step 4 – Call a tool from a controller:

import io.modelcontextprotocol.client.McpClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/agent")
public class AgentController {
    @Autowired
    private McpClient mcpClient;

    @GetMapping("/call-tool")
    public String callTool(@RequestParam String task) {
        // The large model decides which tool to invoke based on the MCP definitions
        return mcpClient.execute(task);
    }
}

With MCP, no custom parsing logic is required, and tool‑calling accuracy surpasses the manual approach.

3. Three Error‑Prevention Measures (Boost Accuracy >95%)

Parameter Pre‑validation

Each tool validates its inputs before execution. Example for version format validation:

@McpTool(name = "search_spring_doc")
public String searchSpringDoc(String version) {
    if (!version.matches("\\d+\\.\\d+\\.\\d+")) {
        return "Parameter error: invalid version format, e.g., 3.2.0";
    }
    // actual query logic
}

Call Audit Logging

An @Aspect logs every tool invocation, including name, parameters, duration, and result or error:

@Aspect
@Component
public class McpToolLogAspect {
    @Around("@annotation(mcpTool)")
    public Object logToolCall(ProceedingJoinPoint joinPoint, McpTool mcpTool) throws Throwable {
        String toolName = mcpTool.name();
        Object[] args = joinPoint.getArgs();
        long startTime = System.currentTimeMillis();
        try {
            Object result = joinPoint.proceed();
            log.info("Tool call success: {}, params: {}, time: {}ms, result: {}", toolName, args, System.currentTimeMillis() - startTime, result);
            return result;
        } catch (Exception e) {
            log.error("Tool call failure: {}, params: {}, time: {}ms, error: {}", toolName, args, System.currentTimeMillis() - startTime, e.getMessage());
            return "Tool call failed: " + e.getMessage();
        }
    }
}

Call‑Count Limiting

To avoid infinite loops, a maximum of three tool calls per task is enforced:

int maxCallCount = 3;
int callCount = 0;
String result = "";
while (callCount < maxCallCount) {
    result = mcpClient.execute(task);
    if (!result.contains("tool call failed")) {
        break;
    }
    callCount++;
}
if (callCount >= maxCallCount) {
    result = "Too many tool calls, please handle manually";
}

4. Tool‑Calling Best Practices

Limit the number of tools : Keep the set under five, each dedicated to a single responsibility.

Provide detailed tool descriptions : Clearly state usage scenarios and parameter requirements.

Secure dangerous tools : Add approval workflows for actions like command execution or file deletion.

Regularly review tool‑call logs : Identify frequent mistakes and refine prompts or tool definitions accordingly.

Conclusion

Tool calling is a core capability for deploying AI agents in real‑world tasks. Prompt engineering establishes a solid baseline, MCP offers a standardized, multi‑model solution, and the three defensive measures push accuracy beyond 95%. The next article will cover RAG and context engineering for handling agent memory and hallucinations.