Tool Use: Agentic Capabilities and Protocols

Tool Use (also known as Function Calling) is the mechanism by which a Large Language Model (LLM) transcends static text generation to perform deterministic actions in the physical or digital world. It transforms the model from a chatbot into a reasoning engine capable of orchestrating complex workflows.

1. How it Works: The Mechanics

The interaction follows a structured Observe-Reason-Act loop. In the Wikantik ecosystem, this is facilitated by the Model Context Protocol (MCP).

The Tool Call Loop

1. Intent Detection: The model identifies that a user request requires external data (e.g., "Find all pages in the finance cluster") or a mutating action (e.g., "Verify this page").
2. Schema Selection: The model selects the appropriate tool based on JSON schema descriptions provided in the system prompt.
3. Parameter Generation: The model generates the arguments for the tool call, adhering to the required types and formats.
4. Dispatch & Execution: The orchestrator (the client interface) routes the request to the relevant MCP server (Knowledge or Admin). The server executes the deterministic Java code.
5. Observation: The system returns the tool result (the observation) to the model.
6. Final Response: The model reasons over the observation to either provide a final answer or initiate another tool call.

Schema Enforcement

Tools are defined using JSON Schema, which acts as the contract between the model and the code.

• In Python: Tools are often defined using Pydantic models, which are then converted to JSON schemas for the LLM.
• In Java (Wikantik): Tools implement the McpTool interface, which provides a definition() method returning a structured McpSchema.Tool object.

2. How to Develop Tools: The Developer's Path

Developing new capabilities for Wikantik agents involves extending the MCP surface.

The McpTool Interface

Every tool must implement the com.wikantik.mcp.tools.McpTool interface:

public interface McpTool {
    String name(); // The snake_case name used by the agent
    McpSchema.Tool definition(); // The JSON schema description and arguments
    McpSchema.CallToolResult execute(Map<String, Object> arguments); // The implementation logic
}

Strategic Placement

• Read-Only Tools: Live in wikantik-knowledge and focus on retrieval.
• Mutating/Admin Tools: Live in wikantik-admin-mcp and handle edits.

For a deep dive into the 36+ tools available and how to wire them, see MCP Integration.

Design Principles (See Good MCP Design)

• Compound Operations: Bundle mechanical loops on the server. A single verify_pages call is more efficient than the agent calling check_link forty times.
• Server vs. Agent Work: Put deterministic logic (sorting, filtering, iterating) on the server. Save the agent's tokens for judgment and content generation.
• Idempotency: Mutating tools should be safe to retry. Writing the same content twice should not result in duplicate pages or errors.

3. How to Utilize Tools: The Agentic Strategy

Effective tool use requires the agent to be "MCP-aware"—knowing which tools to reach for and when.

Selection Strategy (See Finding the Right MCP Tool)

• Orientation: Use get_page_for_agent instead of get_page for initial research. It provides a token-budgeted summary and metadata without pulling the full Markdown body.
• Retrieval: Use retrieve_context for natural language queries and search_knowledge for structured entity lookups.
• Navigation: Use list_pages_by_filter or traverse_relations to move through the wiki's hierarchy.

Error Handling & Hallucination Mitigation

A robust agentic loop does not crash on a malformed tool call; it uses the error as feedback.

• Validation Errors: If the model omits a required argument, the server returns a schema error. The model sees this and self-corrects in the next turn.
• Hallucinated Tools: If the model calls a non-existent tool, the orchestrator provides a list of available tools to nudge the model back onto the valid path.

Security: Human-in-the-Loop (HITL)

For high-stakes environments, mutating tools require explicit user approval. The orchestrator pauses the execution, presents the proposed arguments to the human, and only proceeds upon confirmation.

---

See Also:

• Writing a New MCP Tool (Runbook)
• Agentic Architecture
• Tool Calling (Technical Deep Dive)
• MCP Integration (Implementation Guide)