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 Finding the Right MCP Tool?".

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 (in wikantik-mcp-core):

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

In practice you extend com.wikantik.mcp.AbstractMcpTool (also in wikantik-mcp-core) and implement doExecute( Map ) instead of execute: the base class makes execute final, logs unexpected exceptions and returns the standard error envelope, and supplies the READ_ONLY_ANNOTATIONS constant. Write tools that attribute saves to the calling agent extend DefaultAuthorTool (admin module), which implements AuthorConfigurable; the server injects the MCP client's clientInfo.name as the default author before each call.

Read tools live in wikantik-knowledge/src/main/java/com/wikantik/knowledge/mcp/ alongside GetPageByIdTool, ListClustersTool, and the others. Write tools live in wikantik-admin-mcp/src/main/java/com/wikantik/mcp/tools/ alongside MarkPageVerifiedTool and WritePagesTool. QueryNodesTool and SearchKnowledgeTool are shared: they live in wikantik-mcp-core and both endpoints register them (the admin copy with the inclusion-policy bypass on).

Registration happens in the matching place:

• /knowledge-mcp — KnowledgeMcpInitializer.assembleTools( KnowledgeToolDeps ) calls five add*Tools methods (Knowledge Graph, retrieval, structural spine, projection and bundle, ontology and citation). Each adds its tools only when the service they need is configured, so the endpoint advertises fewer tools on a partial deployment. The tools take a PageViewGate, because this endpoint enforces page view ACLs as an anonymous guest.
• /wikantik-admin-mcp — McpToolRegistry builds two lists: readOnlyTools() (no author injection) and authorConfigurableTools(). McpServerInitializer registers both with the MCP server. Tools that need the Knowledge Graph or the query-log reader are added only when those are wired; rename_cluster, list_content_opportunities and snooze_opportunity are registered unconditionally and refuse at call time instead.

The checks a new tool trips

These apply to the admin endpoint, whose instructions text is a file (wikantik-admin-mcp/src/main/resources/wikantik-mcp-instructions.txt):

Check	Fails when
InstructionsRegistryDriftTest (unit)	a registered tool is not mentioned by name in the instructions file, or the file mentions a tool-shaped name that is not registered. It adds the KG-conditional tools to its expected set by hand, because the unit-test engine does not wire them
McpInstructionsDriftIT (integration)	the same two-way diff, against a deployed server's instructions and tools/list
McpProtocolIT.EXPECTED_TOOLS (integration)	tools/list does not equal that set exactly
McpToolRegistryTest (unit)	names are not unique, a definition is missing, or fewer than 16 tools register (it does not pin an exact count)

A new tool-name prefix (say archive_) must be added to TOOL_NAME_PREFIXES in both McpServerInitializer and McpInstructionsDriftIT, or the drift checks will not see it. The knowledge endpoint has no instructions file (its instructions string is inline in KnowledgeMcpInitializer) and no exact-count test; KnowledgeMcpToolAssemblyTest covers the gating and ToolDescriptionRoutingTest locks routing hints into descriptions. See MCP Audit Tools for the full list of checks.

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.
• Counts. docs/admin/McpAgents.md is the one document that owns the tool counts; other documents link to it rather than repeating the numbers.

Pitfalls

The frontmatter pitfalls capture the failure modes. The most common in practice is the registration omission — the tool compiles, the unit test passes, but the initializer or registry never adds it. Cross-check by calling tools/list on a running server, which is what McpProtocolIT does for the admin endpoint.

---

Cluster Hub: Agent Cookbook (agent-cookbook)