feat: new tool to perform apilookup (latest APIs / SDKs / language features etc) https://github.com/BeehiveInnovations/zen-mcp-server/issues/204

README.md

@@ -220,6 +220,7 @@ Zen activates any provider that has credentials in your `.env`. See `.env.exampl
 - **[`docgen`](docs/tools/docgen.md)** - Generate documentation with complexity analysis
 
 **Utilities**
+- **[`apilookup`](docs/tools/apilookup.md)** - Forces current-year API/SDK documentation lookups, prevents outdated training data responses
 - **[`challenge`](docs/tools/challenge.md)** - Prevent "You're absolutely right!" responses with critical analysis
 - **[`tracer`](docs/tools/tracer.md)** *(disabled by default - [enable](#tool-configuration))* - Static analysis prompts for call-flow mapping
 
@@ -233,6 +234,7 @@ To optimize context window usage, only essential tools are enabled by default:
 **Enabled by default:**
 - `chat`, `thinkdeep`, `planner`, `consensus` - Core collaboration tools
 - `codereview`, `precommit`, `debug` - Essential code quality tools
+- `apilookup` - Rapid API/SDK information lookup
 - `challenge` - Critical thinking utility
 
 **Disabled by default:**

docs/tools/apilookup.md

@@ -0,0 +1,96 @@
+# API Lookup Tool
+
+The `apilookup` tool ensures you get **current, accurate API/SDK documentation** by forcing the AI to search for the latest information rather than relying on outdated training data. This is especially critical for OS-tied APIs (iOS, macOS, Android, etc.) where the AI's knowledge cutoff may be months or years old.
+
+## Why Use This Tool?
+
+### Without Zen (Using Standard AI)
+```
+User: "How do I add glass look to a button in Swift?"
+
+AI: [Searches based on training data knowledge cutoff]
+    "SwiftUI glass morphism frosted glass effect button iOS 18 2025"
+
+Result: You get outdated APIs for iOS 18, which may not work with current iOS 19+
+```
+
+### With Zen (Using apilookup)
+```
+User: "use apilookup how do I add glass look to a button in swift?"
+
+AI: Step 1 - Search: "what is the latest iOS version 2025"
+    → Finds: iOS 19 is current
+
+    Step 2 - Search: "iOS 19 SwiftUI glass effect button 2025"
+    → Gets current APIs specific to iOS 19
+
+Result: You get the correct, current APIs that work with today's iOS version
+```
+
+## Key Features
+
+### 1. **OS Version Detection** (Critical!)
+For any OS-tied request (iOS, macOS, Windows, Android, watchOS, tvOS), `apilookup` **MUST**:
+- First search for the current OS version ("what is the latest iOS version 2025")
+- **Never** rely on the AI's training data for version numbers
+- Only after confirming current version, search for APIs/SDKs for that specific version
+
+### 2. **Authoritative Sources Only**
+Prioritizes official documentation:
+- Project documentation sites
+- GitHub repositories
+- Package registries (npm, PyPI, crates.io, Maven Central, etc.)
+- Official blogs and release notes
+
+### 3. **Actionable, Concise Results**
+- Current version numbers and release dates
+- Breaking changes and migration notes
+- Code examples and configuration options
+- Deprecation warnings and security advisories
+
+## When to Use
+
+- You need current API/SDK documentation or version info
+- You're working with OS-specific frameworks (SwiftUI, UIKit, Jetpack Compose, etc.)
+- You want to verify which version supports a feature
+- You need migration guides or breaking change notes
+- You're checking for deprecations or security advisories
+
+## Usage Examples
+
+### OS-Specific APIs
+```
+use apilookup how do I add glass look to a button in swift?
+use apilookup what's the latest way to handle permissions in Android?
+use apilookup how do I use the new macOS window management APIs?
+```
+
+### Library/Framework Versions
+```
+use apilookup find the latest Stripe Python SDK version and note any breaking changes since v7
+use apilookup what's the current AWS CDK release and list migration steps from v2
+use apilookup check the latest React version and any new hooks introduced in 2025
+```
+
+### Feature Compatibility
+```
+use apilookup does the latest TypeScript support decorators natively?
+use apilookup what's the current status of Swift async/await on Linux?
+```
+
+## How It Works
+
+1. **Receives your query** with API/SDK/framework name
+2. **Injects mandatory instructions** that force current-year searches
+3. **For OS-tied requests**: Requires two-step search (OS version first, then API)
+4. **Returns structured guidance** with instructions for web search
+5. **AI executes searches** and provides authoritative, current documentation
+
+## Output Format
+
+The tool returns JSON with:
+- `status`: "web_lookup_needed"
+- `instructions`: Detailed search strategy and requirements
+- `user_prompt`: Your original request
+
+The AI then performs the actual web searches and synthesizes the results into actionable documentation.

server.py

@@ -49,6 +49,7 @@ from config import (  # noqa: E402
 )
 from tools import (  # noqa: E402
     AnalyzeTool,
+    LookupTool,
     ChallengeTool,
     ChatTool,
     CLinkTool,
@@ -272,6 +273,7 @@ TOOLS = {
     "tracer": TracerTool(),  # Static call path prediction and control flow analysis
     "testgen": TestGenTool(),  # Step-by-step test generation workflow with expert validation
     "challenge": ChallengeTool(),  # Critical challenge prompt wrapper to avoid automatic agreement
+    "apilookup": LookupTool(),  # Quick web/API lookup instructions
     "listmodels": ListModelsTool(),  # List all available AI models by provider
     "version": VersionTool(),  # Display server version and system information
 }
@@ -354,6 +356,11 @@ PROMPT_TEMPLATES = {
         "description": "Challenge a statement critically without automatic agreement",
         "template": "Challenge this statement critically",
     },
+    "apilookup": {
+        "name": "apilookup",
+        "description": "Look up the latest API or SDK information",
+        "template": "Lookup latest API docs for {model}",
+    },
     "listmodels": {
         "name": "listmodels",
         "description": "List available AI models",

tools/__init__.py

@@ -3,6 +3,7 @@ Tool implementations for Zen MCP Server
 """
 
 from .analyze import AnalyzeTool
+from .apilookup import LookupTool
 from .challenge import ChallengeTool
 from .chat import ChatTool
 from .clink import CLinkTool
@@ -26,6 +27,7 @@ __all__ = [
     "DebugIssueTool",
     "DocgenTool",
     "AnalyzeTool",
+    "LookupTool",
     "ChatTool",
     "CLinkTool",
     "ConsensusTool",

tools/apilookup.py

@@ -0,0 +1,122 @@
+"""API lookup tool - quickly gather the latest API/SDK information."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field
+
+from config import TEMPERATURE_ANALYTICAL
+from tools.shared.base_models import ToolRequest
+from tools.simple.base import SimpleTool
+
+if TYPE_CHECKING:
+    from tools.models import ToolModelCategory
+
+
+LOOKUP_FIELD_DESCRIPTIONS = {
+    "prompt": "The API, SDK, library, framework, or technology you need current documentation, version info, breaking changes, or migration guidance for.",
+}
+
+
+class LookupRequest(ToolRequest):
+    prompt: str = Field(..., description=LOOKUP_FIELD_DESCRIPTIONS["prompt"])
+
+
+LOOKUP_PROMPT = """
+MANDATORY: You MUST perform this research in a SEPARATE SUB-AGENT SUB-PROCESS using your web search tool.
+
+MISSION:
+Research the latest, most authoritative documentation for the requested API, SDK, library, framework, programming language feature, or tool to answer the user's question accurately using a SUB-AGENT in a separate process.
+
+STRATEGY:
+- IMPORTANT: Begin by determining today's date and current year
+- MANDATORY FOR OS-TIED APIS/SDKs: If the request involves iOS, macOS, Windows, Linux, Android, watchOS, tvOS, or any OS-specific framework/API:
+  * FIRST perform a web search to determine "what is the latest [OS name] version [current year]"
+  * DO NOT rely on your training data or knowledge cutoff for OS versions - you MUST search for current information
+  * ONLY AFTER confirming the current OS version, search for APIs/SDKs/frameworks for that specific version
+  * Example workflow: Search "latest iOS version [current year]" → Find current version → Then search "[current iOS version] SwiftUI glass effect button [current year]"
+- MANDATORY FOR MAJOR FRAMEWORKS/LANGUAGES: For rapidly-evolving ecosystems, verify current stable version:
+  * Languages: Node.js, Python, Ruby, Rust, Go, Java, .NET/C#, PHP, Kotlin, Swift
+  * Web frameworks: React, Vue, Angular, Next.js, Nuxt, Svelte, SvelteKit, Remix, Astro, SolidJS
+  * Backend frameworks: Django, Flask, FastAPI, Rails, Laravel, Spring Boot, Express, NestJS, Axum
+  * Mobile: Flutter, React Native, Jetpack Compose, SwiftUI
+  * Build tools: Vite, Webpack, esbuild, Turbopack, Rollup
+  * Package managers: npm, pnpm, yarn, pip, cargo, go modules, maven, gradle
+  * Search pattern: "latest [framework/language/SDK] version [current year]" BEFORE searching for specific APIs
+  * ONLY consider articles, documentation, and resources dated within the current year or most recent release cycle
+  * Ignore or deprioritize results from previous years unless they are still the current official documentation
+- ALWAYS find current official documentation, release notes, changelogs, migration guides, and authoritative blog posts. Newest APIs / SDKs released or updated in the current year trump older ones.
+- Prioritize official sources: project documentation sites, GitHub repositories, package registries (npm, PyPI, crates.io, Maven Central, NuGet, RubyGems, Packagist, etc.), and official blogs
+- Check version-specific documentation when relevant and add current year to ensure latest docs are retrieved (e.g., "React docs [current year]", "Python what's new [current year]", "TypeScript breaking changes [current year]", "Next.js app router [current year]")
+- Look for recent Stack Overflow discussions, GitHub issues, RFC documents, or official discussion forums when official docs are incomplete
+- Cross-reference multiple sources to validate syntax, method signatures, configuration options, and best practices
+- Search for deprecation warnings, security advisories, or migration paths between major versions
+- If latest, more current, authoritative information has been found: STOP looking further
+- ALWAYS cite authoritative sources with links (official docs, changelogs, GitHub releases, package registry pages)
+""".strip()
+
+
+class LookupTool(SimpleTool):
+    """Simple tool that wraps user queries with API lookup instructions."""
+
+    def get_name(self) -> str:
+        return "apilookup"
+
+    def get_description(self) -> str:
+        return (
+            "Use this tool automatically when you need current API/SDK documentation, latest version info, breaking changes, deprecations, migration guides, or official release notes. "
+            "This tool searches authoritative sources (official docs, GitHub, package registries) to ensure up-to-date accuracy."
+        )
+
+    def get_system_prompt(self) -> str:
+        return ""
+
+    def get_default_temperature(self) -> float:
+        return TEMPERATURE_ANALYTICAL
+
+    def requires_model(self) -> bool:
+        return False
+
+    def get_model_category(self) -> "ToolModelCategory":
+        from tools.models import ToolModelCategory
+
+        return ToolModelCategory.FAST_RESPONSE
+
+    def get_request_model(self):
+        return LookupRequest
+
+    def get_tool_fields(self) -> dict[str, dict[str, Any]]:
+        return {
+            "prompt": {
+                "type": "string",
+                "description": LOOKUP_FIELD_DESCRIPTIONS["prompt"],
+            }
+        }
+
+    async def prepare_prompt(self, request) -> str:  # pragma: no cover - not used
+        return ""
+
+    def get_input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "description": LOOKUP_FIELD_DESCRIPTIONS["prompt"],
+                },
+            },
+            "required": ["prompt"],
+        }
+
+    async def execute(self, arguments: dict[str, Any]) -> list:
+        from mcp.types import TextContent
+
+        request = self.get_request_model()(**arguments)
+        response = {
+            "status": "web_lookup_needed",
+            "instructions": LOOKUP_PROMPT,
+            "user_prompt": request.prompt,
+        }
+        return [TextContent(type="text", text=json.dumps(response, ensure_ascii=False, indent=2))]