Tool Calling & MCP

What is Tool Calling, and What Problem Does It Solve?

An LLM generates text. It cannot query your database, check an order status, call a payment gateway, or read a file — it has no access to the outside world. Tool calling (also called function calling) is the mechanism that closes this gap: you describe available tools to the model, and the model responds with a structured request to invoke one — including the arguments, extracted from the conversation. Your code executes the tool, returns the result, and the model incorporates it into its next response.

The model never executes anything. It decides which tool to call and what arguments to pass. Your application decides whether to actually execute it, validates the arguments, runs the code, and returns the result. The model is the decision-maker; your code is the executor.

/*
 * BEFORE — a custom integration per external capability.
 * The LLM has no way to check order status, so you hardcode the lookup into
 * the prompt pipeline. Every new capability means new glue code, new prompt
 * rewiring, and a growing if/else chain that routes user intent to Java methods.
 */
if (userMessage.contains("order status")) {
    Order order = orderService.findByCustomerLastOrder(customerId);
    String prompt = "The customer's order #" + order.id()
        + " is " + order.status() + ". Respond to: " + userMessage;
    return chatClient.prompt().user(prompt).call().content();
} else if (userMessage.contains("return")) {
    // another branch, another hardcoded integration...
}

/*
 * AFTER — tool calling. You describe the tools; the model decides when to use them.
 * Adding a new capability means adding a new @McpTool method — no prompt rewiring,
 * no if/else routing, no glue code.
 */
@Component
public class OrderTools {

    private final OrderService orderService;

    public OrderTools(OrderService orderService) {
        this.orderService = orderService;
    }

    @McpTool(description = "Look up the current status of a customer order by order ID")
    public OrderStatusResponse getOrderStatus(
            @McpToolParam(description = "The order ID to look up") Long orderId) {
        Order order = orderService.findById(orderId);
        return new OrderStatusResponse(order.id(), order.status(), order.estimatedDelivery());
    }
}

public record OrderStatusResponse(Long orderId, String status, LocalDate estimatedDelivery) {}

How Tool Calling Works — The Loop

Tool calling is not a single request/response. It is a multi-turn loop between your application, the model, and your tools:

/*
 *  1. Your app sends the user message + a list of available tools (with schemas)
 *     to the model.
 *
 *  2. The model examines the message and decides:
 *     - Respond directly (no tool needed), OR
 *     - Request a tool call: { "tool": "getOrderStatus", "arguments": { "orderId": 4821 } }
 *
 *  3. Your app receives the tool call request, validates the arguments,
 *     executes the Java method, and sends the result back to the model.
 *
 *  4. The model incorporates the tool result into its response and replies
 *     to the user: "Your order #4821 is currently being shipped and should
 *     arrive by Friday."
 *
 *  5. The model may chain multiple tool calls in a single turn — e.g. look up
 *     the order, then check the return policy, then compose a response.
 *
 *  USER ──▶ APP ──▶ MODEL
 *                     │
 *                     ▼ (tool call request)
 *            APP ◀── MODEL
 *             │
 *             ▼ (execute tool, return result)
 *            APP ──▶ MODEL
 *                     │
 *                     ▼ (final response)
 *  USER ◀── APP ◀── MODEL
 */

MCP — The Model Context Protocol

MCP is an open standard (created by Anthropic, now part of the Linux Foundation) that defines how AI applications discover and interact with external tools, data sources, and prompts. It replaces the ad-hoc integration pattern where every tool has a different schema and every provider has a different calling convention.

Architecture

What an MCP server exposes

Transport options

Building an MCP Server with Spring AI

<!-- pom.xml — MCP server starter -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

# application.properties
spring.ai.mcp.server.name=ecommerce-tools
spring.ai.mcp.server.version=1.0.0

// Tools are plain Spring beans annotated with @McpTool.
// Spring AI auto-discovers them, generates the JSON schema from the method
// signature, and registers them with the MCP server at startup.

@Component
public class ProductTools {

    private final ProductRepository productRepository;

    public ProductTools(ProductRepository productRepository) {
        this.productRepository = productRepository;
    }

    @McpTool(description = "Search products by name or category. Returns matching products with prices.")
    public List<ProductSummary> searchProducts(
            @McpToolParam(description = "Search query — product name, category, or keyword")
            String query,
            @McpToolParam(description = "Maximum number of results", required = false)
            Integer maxResults) {

        int limit = (maxResults != null) ? maxResults : 10;
        return productRepository.searchByNameOrCategory(query).stream()
            .limit(limit)
            .map(p -> new ProductSummary(p.id(), p.name(), p.price(), p.category()))
            .toList();
    }

    @McpTool(description = "Get full details of a specific product by its ID")
    public Product getProductById(
            @McpToolParam(description = "The product ID") Long productId) {
        return productRepository.findById(productId)
            .orElseThrow(() -> new IllegalArgumentException("Product not found: " + productId));
    }
}

public record ProductSummary(Long id, String name, BigDecimal price, String category) {}

Exposing resources

@Component
public class OrderResources {

    private final OrderService orderService;

    public OrderResources(OrderService orderService) {
        this.orderService = orderService;
    }

    @McpResource(uri = "orders://{orderId}",
                 description = "Full order details including items, totals, and shipping address")
    public Order getOrder(Long orderId) {
        return orderService.findById(orderId);
    }
}

Client Side — Consuming MCP Tools

An MCP client connects to one or more MCP servers, discovers their tools, and makes them available to the ChatClient. Spring AI auto-configures this.

# application.properties — connect to a remote MCP server
spring.ai.mcp.client.streamable-http.connections.ecommerce.url=http://localhost:8080

// The ChatClient automatically sees tools from connected MCP servers.
// No manual wiring needed — Spring AI resolves them at startup.
@Service
public class CustomerSupportService {

    private final ChatClient chatClient;

    public CustomerSupportService(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("""
                You are a customer support agent for an e-commerce platform.
                Use the available tools to look up order status, search products,
                and retrieve order details. Always verify information before
                responding to the customer.
                """)
            .build();
    }

    public String handleCustomerQuery(String customerMessage) {
        return chatClient.prompt()
            .user(customerMessage)
            .call()
            .content();
        // If the model decides it needs to check an order status or search
        // products, it will call the MCP tools automatically — the loop
        // described in Section 1 happens inside .call().
    }
}

// claude_desktop_config.json
{
  "mcpServers": {
    "ecommerce": {
      "command": "java",
      "args": ["-jar", "path/to/ecommerce-tools.jar"]
    }
  }
}

Security — Tools Are an Attack Surface

Every @McpTool method is code that an LLM can trigger. The model decides when to call it and what arguments to pass — and those arguments come from user input interpreted by the model. This makes tool inputs fundamentally untrusted.

Best Practices

✅ Do write precise, unambiguous descriptions on @McpTool and @McpToolParam. The description is the only thing the model reads to decide whether to call the tool — a vague description leads to wrong tool selection.

✅ Do return records from tools. Spring AI serialises them to JSON via Jackson automatically, and the model can interpret the structured result cleanly.

✅ Do validate all tool arguments as untrusted input. The model decides what to pass — your code decides whether to accept it.

✅ Do keep tools small and focused. A tool that does one thing well is easier for the model to select correctly than a tool that accepts a mode parameter and does five different things.

✅ Do use STDIO for local development and Streamable HTTP for production deployment. STDIO requires no network, no port, and no auth — the host launches your JAR directly.

❌ Don't expose write operations (delete, update, payment) as tools without human-in-the-loop confirmation. The model can decide to call a tool that modifies state — make destructive actions require explicit user approval.

❌ Don't return sensitive data in tool responses. Everything returned from a tool is visible to the model and may appear in the output to the user.

❌ Don't build one large tool with many optional parameters. The model selects better from several small, well-described tools than from one Swiss-army-knife tool with a complex parameter schema.

Interview Questions