Provides instant, offline-first access to Apple Developer Documentation, including symbol search across Apple frameworks, rich documentation retrieval, and technology discovery.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@apple-docs Get docs for SwiftUI's NavigationStack"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A high-performance Model Context Protocol (MCP) server and Antigravity plugin providing instant, offline-first access to Apple Developer Documentation. Features embedded SQLite FTS5 symbol search, wildcard matching, a rich DocC AST-to-Markdown parser, and optional multimodal Gemini semantic embeddings.
🚀 Sub-Millisecond Symbol Search: Pre-indexed SQLite database (apple-docs.db) with FTS5 BM25 scoring over 100,000+ symbols across core Apple frameworks (SwiftUI, UIKit, Foundation, SwiftData, Combine, AppKit, Observation, CoreLocation).
🌐 Global Search by Default: AI agents can search symbols immediately without being forced to run choose_technology first.
🎯 Scoped Search When Desired: Search globally or narrow results by passing framework: "SwiftUI" or choosing an active technology.
📄 Rich DocC AST-to-Markdown Formatter: Formats official Apple documentation into clean, context-optimized Markdown complete with:
Syntax-highlighted Swift declarations (```swift ... ```)
GitHub-style deprecation alerts (> [!WARNING]) with modern replacements
Formatted parameter documentation (### Parameters)
Official Apple discussion notes and code examples
🖼️ Multimodal UI Layout Previews: Leverages gemini-embedding-2 to embed Apple's diagrams, layout previews, and HIG screenshots. Agents can query visual concepts and receive rendered  markdown inline.
🧠 Hybrid Semantic Search (Optional): When GEMINI_API_KEY or Google Application Default Credentials (ADC) are provided, combines lexical BM25 ranking and 3072-dimensional vector similarities via Reciprocal Rank Fusion (RRF).
🛡️ Resilience & Circuit Breaker: Header-based authentication (x-goog-api-key), credential sanitization, and an automatic 30s circuit breaker on API errors/rate-limits with zero-config offline SQLite fallback.
Related MCP server: Apple RAG MCP
Tool | Parameters | Description |
|
| Symbol Lookup Tool. Instant search across symbols with exact-name boosting and wildcard matching ( |
|
| Conceptual & Intent Tool. Natural language search powered by Gemini hybrid vector embeddings. Use when describing behaviors, UI concepts, or when the exact symbol name is unknown. |
|
| Fetches rich documentation for a symbol or path (e.g., |
|
| Browse and filter available Apple technologies and frameworks. |
|
| Optionally scope subsequent searches and lookups to a specific framework (backward compatible). |
| none | View the currently selected technology scope. |
| none | Report MCP server version. |
Install directly with the agy CLI:
# Install from local directory:
agy plugin install .
# Or install from GitHub:
agy plugin install AndrewMason7/apple-doc-pluginOnce installed, the plugin automatically provides:
apple-docs MCP Server: Registered and active for all sessions via bin/launcher.cjs.
apple-docs Skill: Workflow guidance for discovering, searching, and inspecting Apple APIs.
Apple Platform Rules: Enforces API verification and modern framework patterns (e.g. NavigationStack over NavigationView, @Observable over ObservableObject, SwiftData over Core Data).
To validate the plugin structure:
agy plugin validate .Add to your MCP configuration (mcpServers):
{
"mcpServers": {
"apple-docs": {
"command": "node",
"args": ["/path/to/apple-doc-plugin/dist/index.js"],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
}
}
}(Note: GEMINI_API_KEY and ADC are optional. If omitted, pure local SQLite FTS5 runs 100% offline.)
Copy the template to create your local .env:
cp .env.example .envVariable | Required | Description |
| Optional | Google Gemini API key for multimodal 3072-dim embeddings ( |
| Optional | Path to Service Account JSON key for Google Application Default Credentials (ADC). Alternatively, |
| Optional | Custom path to the SQLite index database (defaults to |
The server automatically loads .env natively at startup.
Exact Symbol Lookup:
search_symbols({ "query": "NavigationSplitView" })Scoped Framework Search:
search_symbols({ "query": "ViewController", "framework": "UIKit" })Wildcard Prefix & Suffix Search:
search_symbols({ "query": "Grid*" })
search_symbols({ "query": "*Style" })Platform & Type Filtered Search:
search_symbols({ "query": "View", "platform": "iOS", "symbolType": "protocol" })Direct Documentation Retrieval:
get_documentation({ "path": "NavigationStack", "framework": "SwiftUI" })Conceptual Intent / Behavioral Search (Gemini Semantic):
semantic_search({ "query": "prevent user from dragging sheet down to close", "framework": "SwiftUI" })
semantic_search({ "query": "persist user login credentials securely across reboots" })Multimodal Layout Diagram Queries:
semantic_search({ "query": "three column sidebar split view diagram", "framework": "SwiftUI" })Strictly adhering to Separation of Concerns (SoC):
apple-doc-plugin/
├── bin/
│ └── launcher.cjs # Auto-bootstrapping plugin runner for Antigravity
├── data/
│ └── apple-docs.db # Pre-indexed SQLite database (FTS5 + vectors)
├── rules/
│ └── AGENTS.md # Apple platform guidelines & API rules
├── skills/
│ └── apple-docs/ # Antigravity skill definition & reference guides
├── src/
│ ├── index.ts # CLI stdio MCP server entrypoint
│ ├── apple-client.ts # Apple Developer Documentation HTTP client & file cache
│ ├── apple-client/
│ │ ├── docc-formatter.ts # Pure DocC AST-to-Markdown formatter
│ │ ├── http-client.ts # Resilient HTTP transport with memory caching
│ │ └── types/ # DocC AST data contracts and schema types
│ └── server/
│ ├── app.ts # MCP Server setup & resource registry
│ ├── context.ts # Shared ServerContext
│ ├── db/ # SQLite FTS5 database abstraction layer
│ ├── handlers/ # Dedicated MCP tool handlers (one per tool)
│ └── services/ # Hybrid search, semantic search, and symbol resolution
└── test/ # Comprehensive unit, integration, and stress tests# Compile TypeScript
npm run build
# Run complete test suite (unit, integration, ADC, stress, e2e)
npm test
# Type-check and verify code formatting
npm run check
# Re-format all files with Prettier
npm run format
# (Optional) Re-crawl Apple developer documentation and rebuild index
npm run build:indexThe test suite runs via Node.js native test runner (node --test) covering 72 tests with zero external test runner dependencies.
This project is licensed under the MIT License © 2026 Andrew Mason.
(Optional / Legacy) Select the framework/technology to scope subsequent searches and documentation lookups. In most cases, you can pass framework directly to search_symbols or get_documentation without setting session state.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Technology name/title (e.g. SwiftUI) | |
| identifier | No | Optional technology identifier (e.g. doc://.../SwiftUI) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing side effects. It transparently reveals that the tool sets session state, which will scope subsequent operations. It could say more about persistence or clearing the state, but the core stateful behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, purposeful sentences. The optional/legacy caveat is front-loaded, and the alternative workflow is stated without redundant detail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter state-setting tool, the description covers purpose, side effect, legacy status, and an alternative approach. It does not explain how the state interacts with siblings like current_technology or how to clear it, but the core context an agent needs is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both 'name' and 'identifier'. The description adds no new parameter-level meaning beyond referring to 'framework/technology', so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Select', names the resource, 'framework/technology', and states its purpose: scoping subsequent searches and documentation lookups. The '(Optional / Legacy)' label and the mention of direct framework passing clearly separate it from sibling lookup tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when not to use it: in most cases, agents should pass the framework directly to search_symbols or get_documentation instead of setting session state. It lacks a precise statement of the exact conditions where choose_technology is preferred, but the legacy/optional framing provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Optional / Legacy) Report the currently selected technology in session state
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only says 'Report,' implying a read-only operation, but offers no detail on what happens if no technology is selected, what the output looks like, or any side effects. This is minimal disclosure for a state-reading tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence and easy to parse. The opening '(Optional / Legacy)' adds useful status context but is slightly ambiguous; still, there is no wordiness and the main verb is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema and no annotations, the description states its function clearly and flags its legacy status. An agent can invoke it without knowing parameter names; the only missing detail is the exact return shape, which is minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty required list, so there is nothing to document; the baseline of 4 applies. The description adds no parameter information, which is acceptable given no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a well-defined resource ('the currently selected technology in session state'), which clearly distinguishes it from siblings like choose_technology (selection) and discover_technologies (discovery). It is unambiguous, though it does not explicitly name alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tags the tool as 'Optional / Legacy,' hinting it is not the preferred entry point, but it never states when to call this tool versus choose_technology or discover_technologies, nor does it list exclusions or prerequisites. The agent is left to infer usage from the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore and filter available Apple technologies/frameworks before choosing one
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Optional page number (default 1) | |
| query | No | Optional keyword to filter technologies | |
| pageSize | No | Optional page size (default 25, max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'Explore and filter' but doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, pagination behavior beyond schema hints, or what the output format looks like. The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Explore and filter available Apple technologies/frameworks') and adds context ('before choosing one') without any wasted words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a tool with three parameters for filtering and pagination, the description is incomplete. It doesn't explain what 'technologies/frameworks' entails, how results are structured, or any behavioral constraints. For a discovery tool with filtering capabilities, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (page, pageSize, query) with their types and defaults. The description adds no additional parameter semantics beyond implying filtering via 'query', which is already covered in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Explore and filter') and resource ('available Apple technologies/frameworks'), and distinguishes it from sibling tools by mentioning 'before choosing one' (implying choose_technology is for selection). However, it doesn't explicitly differentiate from other siblings like search_symbols or get_documentation, which might also involve exploration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('before choosing one') by referencing choose_technology, suggesting this tool is for preliminary exploration. However, it lacks explicit guidance on when to use this versus alternatives like search_symbols or get_documentation, and doesn't specify any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed documentation for specific symbols, including Swift syntax declarations, parameters, deprecation notices, and code examples. Can be optionally scoped to a framework directly via the framework argument without needing choose_technology.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Symbol path or relative name (e.g. "View", "GridItem", "documentation/SwiftUI/NavigationStack") | |
| framework | No | Optional framework name (e.g. "SwiftUI", "UIKit"). If omitted, framework is auto-detected from path or local database. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It discloses the main behavioral outcome—returning detailed documentation with syntax, parameters, deprecation notices, and examples—but does not mention error behavior, fallback detection details, or what happens when a symbol is not found. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with useful information: the core purpose, the content of returned documentation, and the framework-scoping behavior. No filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-style lookup tool with no output schema, the description conveys the essential success conditions: required path, optional framework, and what the returned documentation contains. It could mention failure/error behavior or explicitly contrast with search_symbols, but the core calling context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that the framework parameter can scope the documentation directly and avoids the need for choose_technology, which helps an agent decide whether to fill it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieving detailed documentation for specific symbols. It enumerates concrete content (Swift syntax declarations, parameters, deprecation notices, code examples) and distinguishes itself from the sibling choose_technology by noting direct framework scoping is possible without that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when this tool is appropriate: when you need detailed documentation for a specific symbol. It also gives clear context around the framework argument, noting that choose_technology is not required when scoping directly. It does not explicitly exclude search_symbols or semantic_search, but the 'specific symbols' framing supplies enough usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current version information of the Apple Doc MCP server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Get' implies a read operation, the description doesn't specify whether this requires authentication, what the response format looks like, or any rate limits. It lacks details on what 'version information' includes (e.g., server version, API version) or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any fluff or redundant information. It is front-loaded and appropriately sized for a simple tool with no parameters, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does but doesn't provide context on when to use it, what the output entails, or how it fits with sibling tools. For a basic read operation, it meets minimum viability but could be more informative about behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, which is efficient and avoids redundancy. A baseline of 4 is applied as it correctly handles the absence of parameters without adding unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the current version information of the Apple Doc MCP server.' It uses a specific verb ('Get') and identifies the resource ('version information'), though it doesn't explicitly differentiate from sibling tools like 'current_technology' or 'discover_technologies' which might also provide version-related information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for usage, or how it differs from sibling tools such as 'current_technology' or 'discover_technologies', leaving the agent to infer usage based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Apple developer documentation with sub-millisecond symbol-first results across all indexed Apple frameworks. Can be optionally scoped to a framework (via the framework argument or choose_technology). Supports exact symbol resolution, wildcards (*, ?), and conceptual intent searches.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query: can be an exact symbol name ("NavigationSplitView"), wildcard pattern ("Grid*"), or conceptual natural language intent ("background location updates", "sheet dismiss gesture") | |
| platform | No | Optional platform filter (iOS, macOS, watchOS, visionOS) | |
| framework | No | Optional framework name to scope search (e.g. "SwiftUI", "UIKit", "SwiftData"). If omitted, searches across all indexed Apple frameworks. | |
| maxResults | No | Optional maximum number of results (default 20, max 100) | |
| symbolType | No | Optional symbol kind filter (struct, class, protocol, func, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral transparency. It mentions 'sub-millisecond results' and 'conceptual intent searches', but does not disclose limitations such as potential partial matches, ranking behavior, or whether exact symbol resolution guarantees uniqueness. The description is adequate but could be more transparent about what happens when no results are found or how the search treats ambiguous queries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, under 60 words, and front-loads the key differentiator (symbol-first, sub-millisecond). Every sentence adds value, and it avoids redundancy with the schema. It is well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, the description covers the tool's main behavior and query flexibility. The output schema is absent, but the description implicitly explains what results contain (symbols) and mentions scoping options. It doesn't cover error scenarios or edge cases, but for a search tool, this is acceptable. The key aspects are covered, making it complete for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats some parameter semantics (framework scoping via framework or choose_technology) but the input schema already provides detailed descriptions for all parameters (100% coverage). The description adds a little value by explaining the query types (exact, wildcard, conceptual) and mentioning default maxResults, but does not compensate for any gaps. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching Apple developer documentation with symbol-first results. It distinguishes itself from siblings like semantic_search by emphasizing symbol-first and sub-millisecond results, and mentions scoping options that align with sibling tools like choose_technology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for symbol searches) and hints at alternatives like semantic_search for conceptual intent, but it does not explicitly exclude other tools or provide clear 'when not to use' guidance. It implies usage through the query types (exact symbol, wildcard, conceptual), which is helpful but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Apple Developer Documentation by natural language intent, behavioral description, or UI concept (powered by Gemini hybrid embeddings). Use this tool when you do not know the exact Apple API symbol name, or want to query layout patterns and conceptual behavior (e.g. "prevent sheet swipe dismiss", "background location tracking when screen is off", "store auth token securely in keychain", "react useEffect on mount equivalent").
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language description of the desired behavior, UI pattern, or concept (e.g. "three column sidebar split view diagram", "biometric face id authentication") | |
| platform | No | Optional platform filter (iOS, macOS, watchOS, visionOS) | |
| framework | No | Optional framework name to scope semantic search (e.g. "SwiftUI", "UIKit", "LocalAuthentication") | |
| maxResults | No | Optional maximum number of results (default 20, max 100) | |
| symbolType | No | Optional symbol kind filter (struct, class, protocol, func, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses that search is semantic and embedding-based, not exact-name matching, and gives realistic conceptual examples. For a non-mutating search tool this is sufficient, though it does not describe result ordering or output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then immediately gives usage guidance and illustrative examples. Both sentences earn their place, and the examples are varied enough to be useful without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, when to use, query style, and filters via the schema. It is complete enough for an agent to construct a correct request, though it could briefly state what kind of results the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the optional filters are already well documented. The description adds value by clarifying what kinds of query phrasing are acceptable, including cross-framework conceptual equivalents like 'react useEffect on mount equivalent,' which goes beyond the schema's brief examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Search Apple Developer Documentation') and clearly distinguishes the mode: natural language intent, behavioral description, or UI concept rather than exact symbol lookup. This separates it from siblings like search_symbols without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool when you do not know the exact Apple API symbol name or need conceptual/layout queries, with concrete examples. It implies the when-not case but does not explicitly name search_symbols or state 'use that instead for exact matches.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0choose_technologycurrent_technologydiscover_technologiesget_documentationget_versionsearch_symbolssemantic_searchScored across 7 tools
Most tools have clearly distinct roles: symbol search, semantic search, documentation retrieval, and technology discovery. search_symbols and semantic_search have some conceptual overlap since search_symbols also supports intent-based searches, but their descriptions make the primary intended use clear.
Tool names mostly follow a verb_noun pattern like search_symbols, get_documentation, and discover_technologies. current_technology breaks the pattern by being a state query rather than an action, and semantic_search is slightly inconsistent, but the overall convention is predictable.
Seven tools is well-scoped for an Apple documentation server. Each tool serves a clear purpose in the documentation discovery and retrieval workflow, without redundancy or unnecessary bloat.
The core workflows of searching for symbols, searching by concept, and retrieving detailed documentation are fully covered. Missing a dedicated browsing or listing API is a minor gap, but discover_technologies and scoped search largely compensate.
Apple Developer Documentation with Semantic Search, RAG, and AI reranking for MCP clients
The documentation, as a tool your agent can call: 950+ AI-dev guides. Search + fetch tools.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
