This server provides offline-first Apple Developer Documentation lookup and search for coding agents.
Search symbols by exact name, wildcard patterns (Grid*, *Style), or symbol kind, with optional framework/platform filters
Semantic search by natural-language behavior or UI concept, using hybrid vector + lexical search when Gemini is configured
Get detailed documentation for a symbol or DocC path, with disambiguation candidates and CDN fallback
Discover technologies to list indexed frameworks and their symbol counts with pagination
Optionally set/check a session-wide framework via choose_technology / current_technology
Check server version and snapshot freshness with get_version
Run fully offline with the local SQLite database; add a Gemini key to enable embeddings and hybrid search
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.
Offline-first MCP server (and Antigravity plugin) for Apple Developer Documentation.
Local SQLite FTS5 over 65,787 symbols across SwiftUI, UIKit, Foundation, SwiftData, Combine, AppKit, Swift Standard Library, Observation, and CoreLocation. Optional Gemini embeddings for conceptual / visual queries. DocC JSON rendered to Markdown agents can actually use.
Two modes, same binary:
Mode | What you need | What you get |
Offline | Node 22+ and | Fast BM25 + wildcard symbol search, local docs, CDN fallback only when a symbol is missing |
Hybrid | Offline + | Same lexical path, plus vector search, RRF fusion, and UI-layout preview cards |
No API key? It still works offline without a key. That is the point.
Coding agents hallucinate deprecated Apple APIs. Live doc scrapers are accurate until the CDN rate-limits you. This repo keeps a local index for the hot path and only hits Apple or Gemini when it has to.
Ships with:
search_symbols — lexical FTS5 search with exact-name boost, universal wildcard globbing (Grid*, *Style, Navigation*View), kind aliasing (func matches DocC method), runnable copy-paste get_documentation calls, and optional framework / platform filters (never calls Gemini)
semantic_search — natural-language / behavioral queries (hybrid vector + FTS5 with guard against demoting exact symbols on sparse embeddings; falls back to lexical if Gemini credentials are not configured or circuit breaker trips)
get_documentation — point lookup by symbol title (NavigationStack) or path (/documentation/swiftui/view), with disambiguation candidate list for colliding names, and clean error flags on missing symbols
discover_technologies — database-backed discovery listing indexed frameworks with exact symbol counts and valid tool call pagination
index_info / get_version — inspect runtime SQLite database status, symbol count, and freshness
Antigravity skill + rules that tell the agent to verify APIs and prefer NavigationStack, @Observable, SwiftData, Swift Concurrency
Related MCP server: Apple RAG MCP
The MCP tool shape (discover / choose technology, symbol search, get documentation) follows the path opened by MightyDillah/apple-doc-mcp. That server talks to Apple’s live documentation. This project is a separate codebase: local FTS5 index, hybrid ranking, DocC formatter, and Antigravity plugin packaging.
If you want always-fresh docs and npx with no native addon, use that one. If you want offline lookup + ranking + agent rules, use this one.
Node.js 22+ (uses process.loadEnvFile; badge is not decorative)
A working C/C++ toolchain the first time better-sqlite3 compiles (native addon; see docs/TROUBLESHOOTING.md)
Optional: Gemini API key or gcloud auth application-default login
node -v # >= 22
npm install
npm run buildagy plugin install .
# or
agy plugin install AndrewMason7/apple-doc-plugin
agy plugin validate .That registers the MCP server (bin/launcher.cjs), the apple-docs skill, and rules/AGENTS.md.
Build first, then point MCP at the compiled entrypoint. Gemini env is optional.
{
"mcpServers": {
"apple-docs": {
"command": "node",
"args": ["/absolute/path/to/apple-doc-plugin/dist/index.js"],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
}
}
}Omit GEMINI_API_KEY for offline-only. You can also run bin/launcher.cjs if you installed the plugin layout.
Package name on npm is
apple-doc-plugin. Do notnpx apple-doc-mcp-serverand assume it is this repo — that name already belongs to MightyDillah’s live server.
Use the smallest tool that answers the question.
Tool | Use when | Notes |
| You know the behavior or UI concept, not the symbol ( | Preferred for agents. Needs Gemini for the vector half; lexical still runs if the circuit breaker is open or creds missing. Guards against demoting symbols when vectors are sparse (<100 items). |
| You know a name or pattern ( | Always purely local lexical. Exact title match gets a large score boost. Includes runnable copy-paste |
| You already have a symbol or DocC path ( | Point lookup: local SQLite first, Apple DocC CDN if missing. Resolves by title or path. Returns disambiguation candidates if ambiguous and |
| You need the list of indexed frameworks | Database-backed discovery showing exact symbol counts per framework with valid tool JSON pagination. |
| You want an optional session-wide default framework | Optional. Prefer passing |
| You want server version or snapshot freshness | Reports runtime symbol count, indexed frameworks, snapshot build timestamp, and embedding availability. |
semantic_search({ "query": "prevent user from dragging sheet down to close", "framework": "SwiftUI" })
semantic_search({ "query": "three column sidebar split view diagram", "framework": "SwiftUI" })
search_symbols({ "query": "Grid*" })
search_symbols({ "query": "*Style", "framework": "SwiftUI" })
search_symbols({ "query": "Navigation*View", "framework": "SwiftUI" })
search_symbols({ "query": "interactiveDismissDisabled", "symbolType": "func" })
get_documentation({ "path": "NavigationStack" })
get_documentation({ "path": "Button", "framework": "SwiftUI" })
get_documentation({ "path": "/documentation/swiftui/view" })query
├─ sanitize / clamp / escape FTS
├─ lexical: SQLite FTS5 BM25 (+100 exact-title boost)
└─ optional semantic: gemini-embedding-2 (3072-d), cosine vs precomputed L2 norms
└─ skip on missing creds, 401/403/429/5xx/timeout (30s circuit breaker)
fuse with Reciprocal Rank Fusion (k = 60)
optional suffix-wildcard rerank (types & protocols first)
attach visual preview markdown when a media hit exists
slice to maxResultsget_documentation does not go through that fusion path. It is a point lookup: local row → else CDN → DocC AST formatter → Markdown.
The shipped data/apple-docs.db is a snapshot (~99,903 symbols across SwiftUI, UIKit, Foundation, SwiftData, Combine, AppKit, Observation, CoreLocation). It goes stale when Apple ships new APIs.
cp .env.example .env # optional; add GEMINI_API_KEY to also rebuild vectors
npm run build:indexWhat build:index does:
Open SQLite in WAL mode, ensure tables + FTS5 exist
For each configured framework, pull the symbol tree + overview DocC from Apple’s CDN
Upsert symbols and abstracts
If Gemini auth is present: embed documents (asymmetric title/abstract prompts) and referenced UI media
If not: log that this pass is FTS5-only
INSERT INTO symbols_fts(symbols_fts) VALUES('rebuild')
PRAGMA wal_checkpoint(TRUNCATE) + VACUUM
Expect this to take a while and to hit Apple’s CDN. Hybrid rebuilds also cost Gemini embeddings. Run it on a machine with network, then copy the db if you want.
Override the db location with APPLE_DOCS_DB_PATH.
cp .env.example .envVariable | Required | Purpose |
| No | Gemini embeddings ( |
| No | Service-account JSON for ADC. |
| No | Alternate path to the SQLite file (default |
The process loads .env at startup. Credentials are not logged.
apple-doc-plugin/
├── bin/launcher.cjs # Antigravity bootstrap
├── data/apple-docs.db # FTS5 + optional vectors
├── rules/AGENTS.md # modern Apple API rules for agents
├── skills/apple-docs/ # skill + workflow
├── scripts/build-index.ts # corpus rebuild
├── src/
│ ├── index.ts # stdio MCP entry
│ ├── apple-client/ # HTTP + DocC AST → Markdown
│ └── server/
│ ├── handlers/ # one handler per tool
│ ├── services/ # hybrid / semantic / resolution
│ └── db/ # SQLite access
└── test/npm install
npm run build
npm test # Node native runner; currently 82 tests
npm run check # tsc --noEmit + prettier
npm run format
npm run build:index # rebuild the snapshot (network)better-sqlite3 will compile on install. If that fails, see docs/TROUBLESHOOTING.md — you are missing platform build tools, not an MCP bug.
The snapshot is not the entire Apple documentation corpus. Niche frameworks may miss. get_documentation can still fall back to the live DocC CDN for a known path.
Hybrid quality depends on whatever was embedded the last time you ran build:index with Gemini credentials.
Visual previews are derived from media references in Apple’s docs. Treat them as lookup aids, not a HIG replacement.
Native addon (better-sqlite3) requires C++ compilation tools during install.
choose_technology is optional session state. Prefer passing framework directly on the tool call.
MIT © 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…
