Add a Custom Tool

// Add to the tools list in HandleToolsList()
new {
    name = "get_random_fact",
    description = "Get a random fun fact. Optionally specify a category.",
    inputSchema = new {
        type = "object",
        properties = new {
            category = new {
                type = "string",
                description = "Category: science, history, animals, technology, space",
                @enum = new[] { "science", "history", "animals", "technology", "space" }
            }
        },
        required = Array.Empty<string>()
    }
}

// Add to the tools array in handleToolsList()
{
  name: 'get_random_fact',
  description: 'Get a random fun fact. Optionally specify a category.',
  inputSchema: {
    type: 'object',
    properties: {
      category: {
        type: 'string',
        description: 'Category: science, history, animals, technology, space',
        enum: ['science', 'history', 'animals', 'technology', 'space']
      }
    },
    required: []
  }
}

// Add to the tools slice in HandleToolsList()
Tool{
    Name:        "get_random_fact",
    Description: "Get a random fun fact. Optionally specify a category.",
    InputSchema: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "category": map[string]interface{}{
                "type":        "string",
                "description": "Category: science, history, animals, technology, space",
                "enum":        []string{"science", "history", "animals", "technology", "space"},
            },
        },
        "required": []string{},
    },
}

// Add one entry to toolDefinitions(). Nothing else in the server changes, and
// the agent picks the tool up on its next restart without any code change.

new ToolDefinition(
        "get_random_fact",
        "Get a random fun fact. No input required.",
        InputSchema.of(Map.of()))

// A tool that does take arguments looks like this. The last varargs parameter
// lists the required property names.
new ToolDefinition(
        "get_random_fact",
        "Get a random fun fact, optionally about a specific category.",
        InputSchema.of(
                Map.of("category", Property.string("Optional category: 'space', 'animals', 'history'"))))

public static class RandomFactTool
{
    private static readonly Dictionary<string, string[]> Facts = new()
    {
        ["science"] = new[]
        {
            "Honey never spoils. Archaeologists found 3000-year-old honey still edible.",
            "A teaspoon of a neutron star would weigh about 6 billion tons.",
            "Octopuses have three hearts and blue blood.",
        },
        ["history"] = new[]
        {
            "Cleopatra lived closer to the Moon landing than to the Great Pyramid.",
            "Oxford University is older than the Aztec Empire.",
            "Ancient Romans used crushed mouse brains as toothpaste.",
        },
        ["animals"] = new[]
        {
            "A group of flamingos is called a 'flamboyance'.",
            "Cows have best friends and get stressed when separated.",
            "Sea otters hold hands while sleeping to avoid drifting apart.",
        },
        ["technology"] = new[]
        {
            "The first computer bug was a real moth found in a Harvard Mark II in 1947.",
            "Apollo 11's computer had less power than a modern calculator.",
            "The first domain ever registered was symbolics.com in 1985.",
        },
        ["space"] = new[]
        {
            "More stars exist than grains of sand on all Earth's beaches.",
            "A day on Venus is longer than a year on Venus.",
            "Neutron stars can spin at 600 rotations per second.",
        },
    };

    public static string GetRandomFact(string? category = null)
    {
        var rng = Random.Shared;
        if (category != null && Facts.TryGetValue(category, out var list))
            return list[rng.Next(list.Length)];

        var all = Facts.Values.SelectMany(f => f).ToArray();
        return all[rng.Next(all.Length)];
    }
}

const FACTS: Record<string, string[]> = {
  science: [
    'Honey never spoils. 3000-year-old honey was found still edible.',
    'A teaspoon of a neutron star would weigh about 6 billion tons.',
    'Octopuses have three hearts and blue blood.',
  ],
  history: [
    'Cleopatra lived closer to the Moon landing than to the Great Pyramid.',
    'Oxford University is older than the Aztec Empire.',
    'Ancient Romans used crushed mouse brains as toothpaste.',
  ],
  animals: [
    "A group of flamingos is called a 'flamboyance'.",
    'Cows have best friends and get stressed when separated.',
    "Sea otters hold hands while sleeping to avoid drifting apart.",
  ],
  technology: [
    'The first computer bug was a real moth found in a Harvard Mark II in 1947.',
    "Apollo 11's computer had less power than a modern calculator.",
    'The first domain ever registered was symbolics.com in 1985.',
  ],
  space: [
    "More stars exist than grains of sand on all Earth's beaches.",
    'A day on Venus is longer than a year on Venus.',
    'Neutron stars can spin at 600 rotations per second.',
  ],
};

export function getRandomFact(category?: string): string {
  if (category && FACTS[category]) {
    const list = FACTS[category];
    return list[Math.floor(Math.random() * list.length)];
  }
  const all = Object.values(FACTS).flat();
  return all[Math.floor(Math.random() * all.length)];
}

package tools

import "math/rand"

var facts = map[string][]string{
    "science": {
        "Honey never spoils. 3000-year-old honey was found still edible.",
        "A teaspoon of a neutron star would weigh about 6 billion tons.",
        "Octopuses have three hearts and blue blood.",
    },
    "history": {
        "Cleopatra lived closer to the Moon landing than to the Great Pyramid.",
        "Oxford University is older than the Aztec Empire.",
        "Ancient Romans used crushed mouse brains as toothpaste.",
    },
    "animals": {
        "A group of flamingos is called a 'flamboyance'.",
        "Cows have best friends and get stressed when separated.",
        "Sea otters hold hands while sleeping to avoid drifting apart.",
    },
    "technology": {
        "The first computer bug was a real moth in a Harvard Mark II in 1947.",
        "Apollo 11's computer had less power than a modern calculator.",
        "The first domain ever registered was symbolics.com in 1985.",
    },
    "space": {
        "More stars exist than grains of sand on all Earth's beaches.",
        "A day on Venus is longer than a year on Venus.",
        "Neutron stars can spin at 600 rotations per second.",
    },
}

func GetRandomFact(category string) string {
    if list, ok := facts[category]; ok {
        return list[rand.Intn(len(list))]
    }
    var all []string
    for _, v := range facts {
        all = append(all, v...)
    }
    return all[rand.Intn(len(all))]
}

package no.javazone.mcp;

import java.util.List;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;
import org.springframework.stereotype.Component;

// No arguments and no network call, which makes this the tool to reach for when
// you are debugging: if this works and the weather tool does not, the problem is
// upstream, not in your MCP plumbing.
@Component
class RandomFactTool {

    private static final Map<String, List<String>> FACTS = Map.of(
            "space", List.of(
                    "A day on Venus is longer than a year on Venus.",
                    "There are more possible iterations of a game of chess than atoms in the known universe."),
            "animals", List.of(
                    "Octopuses have three hearts and blue blood.",
                    "A group of flamingos is called a 'flamboyance'.",
                    "The heart of a shrimp is located in its head."),
            "history", List.of(
                    "Honey never spoils. Archaeologists have found 3000-year-old honey in Egyptian tombs.",
                    "The shortest war in history lasted 38-45 minutes, between Britain and Zanzibar in 1896.",
                    "Norway once knighted a penguin named Nils Olav."));

    ToolResult call(Map<String, Object> arguments) {
        // An unknown category is not an error - fall back to everything rather
        // than making the model apologise for a guess it could not have known.
        var pool = arguments.get("category") instanceof String c && FACTS.containsKey(c)
                ? FACTS.get(c)
                : FACTS.values().stream().flatMap(List::stream).toList();

        var fact = pool.get(ThreadLocalRandom.current().nextInt(pool.size()));

        return ToolResult.success(fact, Map.of("fact", fact));
    }
}

// In HandleToolsCall(), add a new case:
case "get_random_fact":
    var category = args.TryGetProperty("category", out var cat) ? cat.GetString() : null;
    var fact = RandomFactTool.GetRandomFact(category);
    return new {
        content = new[] { new { type = "text", text = fact } },
        isError = false
    };

// In handleToolsCall(), add a new case:
case 'get_random_fact': {
  const fact = getRandomFact(args.category);
  return {
    content: [{ type: 'text', text: fact }],
    isError: false
  };
}

// In handleToolsCall(), add a new case:
case "get_random_fact":
    category, _ := args["category"].(string)
    fact := tools.GetRandomFact(category)
    return map[string]interface{}{
        "content": []map[string]string{{"type": "text", "text": fact}},
        "isError": false,
    }, nil

// Routing is a map lookup, not a switch. Spring injects each tool, and the
// registry is the only place a tool name appears twice.

private final Map<String, Function<Map<String, Object>, ToolResult>> registry;

McpController(WeatherTool weather, RandomFactTool randomFact, NewsTool news) {
    this.registry = Map.of(
            "get_weather_forecast", weather::call,
            "get_random_fact", randomFact::call,
            "get_news", news::call);
}

private JsonRpcResponse callTool(JsonRpcRequest request) {
    var tool = registry.get(name);
    if (tool == null) {
        // -32602 is "invalid params" - the method existed, the tool name did not.
        return JsonRpcResponse.failure(request.id(), -32602, "Unknown tool: " + name);
    }

    return JsonRpcResponse.ok(request.id(), tool.apply(arguments));
}