Writing a New MCP Tool

The MCP tool surface is the agent-facing API. Every tool added here is callable by any agent that has access to the relevant endpoint, so the bar for landing one is "is this useful enough to justify a slot in the decision tree on FindingTheRightMcpTool?".

When to use this runbook

When you have a concrete new agent operation in mind. Don't write speculative tools — the cost of a never-called tool is a slot wasted in the agent's decision space.

Context

A tool implements com.wikantik.mcp.tools.McpTool:

public interface McpTool {
    String name();
    McpSchema.Tool definition();
    McpSchema.CallToolResult execute( Map< String, Object > arguments );
}

Read tools live in wikantik-knowledge/src/main/java/com/wikantik/knowledge/mcp/ alongside GetPageByIdTool, SearchKnowledgeTool, and the others. Write tools live in wikantik-admin-mcp/src/main/java/com/wikantik/mcp/tools/ alongside MarkPageVerifiedTool and WritePagesTool.

Registration happens in the matching initializer:

• wikantik-knowledge/.../mcp/KnowledgeMcpInitializer — adds tools to the assembled tools list when the relevant manager (StructuralIndexService, ForAgentProjectionService, etc.) is configured.
• wikantik-admin-mcp/.../McpServerInitializer (or the registry it uses) — adds tools and classifies them as read-only or author-configurable.

Walkthrough

The frontmatter steps are the canonical sequence. A few elaborations:

• Description style. The description field is what agents read when picking tools. Phrase it as a trigger condition, not an implementation summary. Bad: "Returns a JSON object containing the page's metadata." Good: "Resolve a canonical_id to the current page descriptor. Prefer this over get_page when citing sources."
• JSON schema strictness. Required vs. optional matters — agents pick required-only paths first. Don't mark a field required unless it's truly required.
• Test pattern. GetPageForAgentToolTest and MarkPageVerifiedToolTest both follow the same template: mock the underlying service, assert name(), definition() shape, error paths (missing argument, unknown id), and a happy-path serialisation check.

Pitfalls

The frontmatter pitfalls capture the failure modes. The most common in practice is the registration omission — the tool compiles, the test passes, but the initializer never adds it. Cross-check by running the relevant McpToolRegistryTest (or the equivalent for knowledge-mcp).