XC-MCP is an intelligent Xcode CLI wrapper that optimizes developer workflows through progressive disclosure, smart caching, and AI-driven learning to address MCP client token limits.
Core Capabilities:
Xcode Project Management: Execute builds with smart defaults, list targets/schemes/configurations, show SDKs, get version info, and clean artifacts with cached logs and learning systems
Simulator Control: Manage iOS simulators with concise summaries, progressive disclosure for full details, boot/shutdown operations with performance tracking, and smart recommendations
Intelligent Caching System: Multi-layer caching with configurable timeouts, comprehensive statistics, cache clearing, and cached response listing
Data Persistence: File-based state persistence across server restarts for cache data and learned patterns
AI-Driven Optimization: Learning from usage patterns, performance metrics tracking (build/boot times), and adaptive intelligence for improved recommendations and workflow efficiency
Provides intelligent Xcode CLI tooling with progressive disclosure, enabling build operations, simulator management, project discovery, and cache management while solving token overflow issues through smart caching and concise summaries
Click on "Install 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., "@XC-MCP: XCode CLI wrapper list available iPhone simulators"
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.
Production-grade MCP server for Xcode workflows — optimized for AI agents with accessibility-first iOS automation
XC-MCP makes Xcode and iOS simulator tooling accessible to AI agents through intelligent context engineering. V3.0.0 adds platform-native defer_loading support — Claude's tool search automatically discovers tools on-demand, minimizing baseline context overhead while maintaining full 29-tool functionality.
Traditional Xcode CLI wrappers dump massive output that exceeds MCP protocol limits:
simctl list: 57,000+ tokens (unusable in MCP context)
Build logs: 135,000+ tokens (catastrophic overflow)
Screenshot-first automation: 170 tokens per screen, 2000ms latency
No state memory between operations
V3.0.0 Architecture:
Platform-native defer_loading on all 29 tools
├─ Claude's tool search discovers tools automatically
├─ Tools loaded on-demand (minimal baseline overhead)
├─ Accessibility-first workflow (50 tokens, 120ms vs 170 tokens, 2000ms)
└─ Workflow tools for common operations (fresh-install, tap-element)Token Efficiency Evolution:
Version | Baseline Tokens | Total Tools | Architecture | Context Available |
Pre-RTFM (v1.2.1) | ~45k | 51 | Individual tools | 3.9% (155k) |
V1.3.2 (RTFM) | ~30k | 51 | Individual + RTFM | 1.5% (170k) |
V2.0.0 | ~18.7k | 28 | Routers + Full Docs | 9.3% (181k) |
V3.0.0 | ~0 | 29 | Platform defer_loading | 100% (200k) |
Key Improvements (V3.0.0):
✅ Platform-native defer_loading - All tools deferred; Claude discovers on-demand
✅ Workflow tools - High-level abstractions for common operations
✅ Zero baseline overhead - Platform handles tool discovery
✅ Accessibility-first automation (3-4x faster, 3-4x cheaper than screenshots)
✅ Progressive disclosure (summaries → cache IDs → full details on demand)
✅ 60% test coverage with comprehensive error handling
Related MCP server: mcp-compressor
# Install globally
npm install -g xc-mcp
# Or run without installation
npx xc-mcpMCP Configuration (Claude Desktop):
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"xc-mcp": {
"command": "npx",
"args": ["-y", "xc-mcp"]
}
}
}Minimal Mode (for Claude Code and other clients that don't support defer_loading):
{
"mcpServers": {
"xc-mcp": {
"command": "npx",
"args": ["-y", "xc-mcp", "--mini"]
}
}
}The --mini flag reduces tool descriptions from ~18.7k tokens to ~540 tokens (~97% reduction). Use rtfm for full documentation on-demand.
Build-Only Mode (for build-focused workflows without UI automation):
{
"mcpServers": {
"xc-mcp": {
"command": "npx",
"args": ["-y", "xc-mcp", "--build-only"]
}
}
}The --build-only flag loads only 11 tools (vs 30): xcodebuild tools, simctl-list, cache, and system tools. Excludes IDB/UI automation and workflow tools. Combine with --mini for maximum reduction: ["--mini", "--build-only"].
XC-MCP returns concise summaries first, with cache IDs for on-demand detail retrieval:
Example: Simulator List (96% token reduction)
// 1. Get summary (2,000 tokens vs 57,000 raw)
simctl-list({ deviceType: "iPhone" })
// Returns:
{
cacheId: "sim-abc123",
summary: { totalDevices: 47, availableDevices: 31, bootedDevices: 1 },
quickAccess: { bootedDevices: [...], recentlyUsed: [...] }
}
// 2. Get full details only if needed
simctl-get-details({
cacheId: "sim-abc123",
detailType: "available-only",
maxDevices: 10
})Example: Build Operations
// 1. Build returns summary + buildId
xcodebuild-build({ projectPath: "./MyApp.xcworkspace", scheme: "MyApp" })
// Returns:
{
buildId: "build-xyz789",
success: true,
summary: { duration: 7075, errorCount: 0, warningCount: 1 }
}
// 2. Access full logs only when debugging
xcodebuild-get-details({ buildId: "build-xyz789", detailType: "full-log" })Discovery Workflow:
// 1. Browse tool categories
rtfm({ categoryName: "build" })
// Returns: List of build tools with brief descriptions
// 2. Get comprehensive docs for specific tool
rtfm({ toolName: "xcodebuild-build" })
// Returns: Full documentation with parameters, examples, related tools
// 3. Execute with consolidated operations
xcodebuild-build({ scheme: "MyApp", configuration: "Debug" })Why RTFM?
Tool descriptions: <10 words + "See rtfm for details"
Full docs retrieved only when needed
80% token savings vs traditional verbose MCP servers
Before V2.0: 21 individual tools
simctl-boot, simctl-shutdown, simctl-create, simctl-delete,
simctl-erase, simctl-clone, simctl-rename, simctl-install,
simctl-uninstall, simctl-launch, simctl-terminate...V2.0: 6 consolidated routers
simctl-device({ operation: "boot" | "shutdown" | "create" | "delete" | "erase" | "clone" | "rename" })
simctl-app({ operation: "install" | "uninstall" | "launch" | "terminate" })
idb-app({ operation: "install" | "uninstall" | "launch" | "terminate" })
cache({ operation: "get-stats" | "get-config" | "set-config" | "clear" })
persistence({ operation: "enable" | "disable" | "status" })
idb-targets({ operation: "list" | "describe" | "connect" | "disconnect" })Result: 40% token reduction through shared parameter schemas and unified documentation.
XC-MCP promotes accessibility-first automation because it:
Encourages better apps: Developers building accessible UIs benefit all users (screen readers, voice control, assistive technologies)
Enables precise AI interaction: Semantic element discovery via accessibility tree vs visual guesswork from screenshots
Improves efficiency: 3-4x faster execution, 3-4x cheaper token cost
Reduces energy usage: Skip computationally expensive image processing entirely
Approach | Tokens | Latency | Use Case |
Accessibility Tree | ~50 | ~120ms | Rich UIs with >3 tappable elements |
Screenshot Analysis | ~170 | ~2000ms | Minimal UIs with ≤1 tappable element |
Efficiency Gain | 3.4x cheaper | 16x faster | When accessibility sufficient |
// 1. ALWAYS assess quality first
accessibility-quality-check({ screenContext: "LoginScreen" })
// Returns:
{
quality: "rich" | "moderate" | "minimal",
recommendation: "accessibility-ready" | "consider-screenshot",
elementCounts: { total: 12, tappable: 8, textFields: 2 }
}
// 2. Decision branch based on quality
if (quality === "rich" || quality === "moderate") {
// Use accessibility tree (faster, cheaper)
idb-ui-find-element({ query: "login" })
// Returns: { centerX: 200, centerY: 400, label: "Login" }
idb-ui-tap({ x: 200, y: 400 })
// Precise coordinate-based interaction
} else if (quality === "minimal") {
// Fall back to screenshot (last resort)
screenshot({ size: "half", screenName: "LoginScreen" })
// Visual analysis when accessibility insufficient
}Why This Matters:
For Users: Encourages inclusive app development benefiting everyone
For AI Agents: Precise semantic targeting vs visual pattern matching
For Efficiency: 50 tokens (accessibility) vs 170 tokens (screenshot)
For Speed: 120ms (accessibility) vs 2000ms (screenshot)
For Energy: Skip image encoding/decoding/analysis entirely
accessibility-quality-check: Rapid assessment without full tree query
Returns: rich (>3 tappable) | moderate (2-3) | minimal (≤1)
Use case: Decision point before screenshot vs accessibility
Cost: ~30 tokens, ~80ms
idb-ui-find-element: Semantic element search by label/identifier
Returns: Tap-ready coordinates (centerX, centerY) with frame boundaries
Use case: Find specific button, field, or cell without visual analysis
Cost: ~40 tokens, ~120ms
idb-ui-describe: Full accessibility tree with progressive disclosure
Operation all: Summary + uiTreeId for full tree retrieval
Operation point: Element details at specific coordinates
Use case: Discover all interactive elements, validate tap coordinates
Cost: ~50 tokens for summary, ~500 tokens for full tree
XC-MCP V3.0 adds the defer_loading: true flag to all 29 tool registrations. Claude's platform-native tool search automatically:
Discovers tools on-demand — No custom tool-search implementation needed
Loads tools when relevant — Based on conversation context
Minimizes baseline overhead — Zero tokens at startup
Use rtfm to get comprehensive documentation for any tool:
// 1. Browse tool categories
rtfm({ categoryName: "build" })
// Returns all build-related tools with descriptions
// 2. Get comprehensive docs for specific tool
rtfm({ toolName: "xcodebuild-build" })
// Returns full documentation with parameters, examples, related tools
// 3. Execute with discovered parameters
xcodebuild-build({ scheme: "MyApp", configuration: "Debug" })Default (V3.0.0): All tools have defer_loading enabled
# Platform discovers and loads tools automatically
# Zero baseline token overheadDisable defer_loading (for debugging/testing):
# Set environment variable to load all tools at startup
export XC_MCP_DEFER_LOADING=false
# All 29 tools loaded immediately (~18.7k tokens)
# Useful for: Testing, debugging, MCP client compatibilityXC-MCP provides 2 high-level workflow tools that combine common operations into single steps:
workflow-tap-element — High-Level Semantic TapCombines accessibility quality check + element search + tap into one operation:
workflow-tap-element({
elementQuery: "Login",
screenContext: "LoginScreen",
inputText: "user@example.com", // optional: type after tap
verifyResult: true // optional: screenshot after action
})
// Does:
// 1. Quality check screen accessibility
// 2. Find element by name/label
// 3. Tap coordinates
// 4. Optionally type text
// 5. Optionally take verification screenshot
// Returns: { success: true, tappedElement: {...}, screenshot?: {...} }Cost: ~90 tokens (vs 130 tokens separately) Latency: ~300ms (vs ~400ms separately) Use case: User login, form submission, navigation flows
workflow-fresh-install — Clean Install WorkflowPerforms complete app refresh: shutdown → (erase) → boot → build → install → launch
workflow-fresh-install({
projectPath: "./MyApp.xcworkspace",
scheme: "MyApp",
simulatorUdid: "...", // optional: auto-detects
eraseSimulator: true, // optional: wipe simulator data
configuration: "Debug",
launchArguments: ["--resetData"]
})
// Does:
// 1. Shutdown simulator if running
// 2. Erase simulator state (if requested)
// 3. Boot simulator fresh
// 4. Build app
// 5. Install app
// 6. Launch app with arguments
// Returns: { success: true, buildTime: 7000, bootTime: 3000, launchTime: 500 }Cost: ~200 tokens (vs 300+ tokens separately) Latency: ~20s (vs 25+ seconds separately) Use case: CI/CD pipelines, clean state testing, fresh debugging sessions
simctl-device — Simulator lifecycle (7 operations)
boot, shutdown, create, delete, erase, clone, rename
Auto-UDID detection, performance tracking, smart defaults
simctl-app — App management (4 operations)
install, uninstall, launch, terminate
Bundle ID resolution, launch arguments, environment variables
idb-app — IDB app operations (4 operations)
install, uninstall, launch, terminate
Physical device + simulator support via IDB
cache — Cache management (4 operations)
get-stats, get-config, set-config, clear
Multi-layer caching (simulator, project, response, build settings)
persistence — Persistence control (3 operations)
enable, disable, status
File-based cache across server restarts
idb-targets — Target management (2 operations)
list, describe, connect, disconnect
Physical device and simulator discovery
Build & Test (6 tools)
xcodebuild-build: Build with progressive disclosure via buildId
xcodebuild-test: Test with filtering, test plans, cache IDs
xcodebuild-clean: Clean build artifacts
xcodebuild-list: List targets/schemes with smart caching
xcodebuild-version: Get Xcode and SDK versions
xcodebuild-get-details: Access cached build/test logs
UI Automation (6 tools)
idb-ui-describe: Accessibility tree queries (all | point operations)
idb-ui-tap: Coordinate-based tapping with percentage conversion
idb-ui-input: Text input with keyboard control
idb-ui-gesture: Swipes, pinches, rotations with coordinate transforms
idb-ui-find-element: Semantic element search (NEW in v2.0)
accessibility-quality-check: Rapid UI richness assessment (NEW in v2.0)
I/O & Media (2 tools)
simctl-io: Screenshots and video recording with semantic naming
screenshot: Vision-optimized base64 screenshots (inline, max 800px)
Discovery & Health (3 tools)
simctl-list: Progressive disclosure simulator listing (96% token reduction)
simctl-get-details: On-demand full simulator data retrieval
simctl-health-check: Xcode environment validation
Utilities (5 tools)
simctl-openurl: Open URLs and deep links
simctl-get-app-container: Get app container paths (bundle, data, group)
simctl-push: Simulate push notifications
rtfm: On-demand comprehensive documentation
Workflow Tools (2 high-level abstractions) - NEW in V3.0.0
workflow-tap-element: High-level semantic tap (find + tap in one call)
workflow-fresh-install: Clean install workflow (shutdown → erase → boot → build → install → launch)
Total: 29 active tools (27 core + 2 workflow abstractions)
// 1. Quality check before choosing approach
accessibility-quality-check({ screenContext: "LoginScreen" })
// → { quality: "rich", tappableElements: 12, textFields: 2 }
// 2. Find email field semantically
idb-ui-find-element({ query: "email" })
// → { centerX: 200, centerY: 150, label: "Email", type: "TextField" }
// 3. Tap and input email
idb-ui-tap({ x: 200, y: 150 })
idb-ui-input({ operation: "text", text: "user@example.com" })
// 4. Find and tap login button
idb-ui-find-element({ query: "login" })
// → { centerX: 200, centerY: 400, label: "Login", type: "Button" }
idb-ui-tap({ x: 200, y: 400 })
// 5. Verify (screenshot only for confirmation, not primary interaction)
screenshot({ screenName: "HomeScreen", state: "LoggedIn" })Efficiency Comparison:
Accessibility approach: 4 queries × 50 tokens = 200 tokens, ~500ms total
Screenshot approach: 3 screenshots × 170 tokens = 510 tokens, ~6000ms total
Savings: 2.5x cheaper, 12x faster
// 1. Browse tool categories
rtfm({ categoryName: "build" })
// Returns:
{
category: "build",
tools: [
{ name: "xcodebuild-build", description: "Build Xcode projects with smart defaults" },
{ name: "xcodebuild-test", description: "Run tests with filtering and test plans" },
...
]
}
// 2. Get comprehensive docs for specific tool
rtfm({ toolName: "xcodebuild-build" })
// Returns:
{
tool: "xcodebuild-build",
description: "Full comprehensive documentation...",
parameters: { projectPath: "...", scheme: "...", configuration: "..." },
examples: [...],
relatedTools: ["xcodebuild-clean", "xcodebuild-get-details"]
}
// 3. Execute with discovered parameters
xcodebuild-build({
projectPath: "./MyApp.xcworkspace",
scheme: "MyApp",
configuration: "Debug"
})// 1. Build returns summary + buildId
xcodebuild-build({
projectPath: "./MyApp.xcworkspace",
scheme: "MyApp"
})
// Returns:
{
buildId: "build-abc123",
success: true,
summary: {
duration: 7075,
errorCount: 0,
warningCount: 1,
configuration: "Debug",
sdk: "iphonesimulator"
},
nextSteps: [
"Build completed successfully",
"Use 'xcodebuild-get-details' with buildId for full logs"
]
}
// 2. Access full logs only when debugging
xcodebuild-get-details({
buildId: "build-abc123",
detailType: "full-log",
maxLines: 100
})
// Returns: Full compiler output, warnings, errorsCopy this into your project's CLAUDE.md to guide AI agents toward optimal XC-MCP usage:
# XC-MCP Optimal Usage Patterns
This project uses XC-MCP for iOS development automation. Follow these patterns for maximum efficiency.
## Tool Discovery
1. **Browse categories**: `rtfm({ categoryName: "build" })` — See all build-related tools
2. **Get tool docs**: `rtfm({ toolName: "xcodebuild-build" })` — Comprehensive documentation
3. **Execute**: Use discovered parameters and operations
## Accessibility-First Automation (MANDATORY)
**ALWAYS assess accessibility quality before taking screenshots:**
1. **Check quality**: `accessibility-quality-check({ screenContext: "LoginScreen" })`
- Returns: `rich` | `moderate` | `minimal`
2. **Decision branch**:
- IF `rich` or `moderate`: Use `idb-ui-find-element` + `idb-ui-tap` (faster, cheaper)
- IF `minimal`: Fall back to `screenshot` (last resort)
3. **Why this matters**:
- Accessibility: 50 tokens, 120ms per query
- Screenshots: 170 tokens, 2000ms per capture
- **3-4x cheaper, 16x faster when accessibility sufficient**
- **Promotes inclusive app development**
## Progressive Disclosure
- Build/test tools return `buildId` or cache IDs
- Use `xcodebuild-get-details` or `simctl-get-details` to drill down
- **Never request full logs upfront** — get summaries first
## Best Practices
- **Let UDID auto-detect** — Don't prompt user for simulator UDIDs
- **Use semantic context** — Include `screenContext`, `appName`, `screenName` parameters
- **Prefer accessibility over screenshots** — Better for efficiency AND app quality
- **Use operation enums** — `simctl-device({ operation: "boot" })` instead of separate tools
## Example: Optimal Login Flow
\`\`\`typescript
// 1. Quality check (30 tokens, 80ms)
accessibility-quality-check({ screenContext: "LoginScreen" })
// 2. IF rich: Semantic search (40 tokens, 120ms)
idb-ui-find-element({ query: "email" })
idb-ui-tap({ x: 200, y: 150 })
idb-ui-input({ operation: "text", text: "user@example.com" })
idb-ui-find-element({ query: "login" })
idb-ui-tap({ x: 200, y: 400 })
// 3. Verify with screenshot only at end (170 tokens, 2000ms)
screenshot({ screenName: "HomeScreen", state: "LoggedIn" })
// Total: ~280 tokens, ~2400ms
// vs Screenshot-first: ~510 tokens, ~6000ms (2.5x slower, 1.8x more expensive)
\`\`\`macOS with Xcode command-line tools
Node.js 18+
Xcode 15+ recommended
Install Xcode CLI tools:
xcode-select --install# Global install (recommended for MCP)
npm install -g xc-mcp
# Or run directly without installation
npx -y xc-mcp
# Local development
git clone https://github.com/conorluddy/xc-mcp.git
cd xc-mcp && npm install && npm run buildClaude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"xc-mcp": {
"command": "npx",
"args": ["-y", "xc-mcp"],
"cwd": "/path/to/your/ios/project"
}
}
}Environment Variables (optional):
XCODE_CLI_MCP_TIMEOUT: Operation timeout in seconds (default: 300)
XCODE_CLI_MCP_LOG_LEVEL: Logging verbosity (debug | info | warn | error)
XCODE_CLI_MCP_CACHE_DIR: Custom cache directory path
XC_MCP_DEFER_LOADING: Enable deferred tool loading (default: true for V3.0)
What Changed:
All 29 tools now have defer_loading: true flag
Claude's platform tool search discovers tools automatically
No custom tool-search implementation needed
Tools loaded on-demand based on conversation context
Migration Path:
Scenario | Action | Notes |
New Projects | No action needed | Platform handles discovery |
Existing Integrations | No action needed | Compatible with V2.x usage |
Debugging/Testing | Set env var | Use |
Usage (same as V2.x):
// V3.0 - Platform discovers tools automatically
// Just use tools as before - Claude's tool search handles discovery
xcodebuild-build({ scheme: "MyApp" })
// Use RTFM for documentation discovery
rtfm({ categoryName: "build" })
rtfm({ toolName: "xcodebuild-build" })
// Disable defer_loading for debugging
export XC_MCP_DEFER_LOADING=falseToken Impact:
Version | Startup | Discovery | Notes |
V2.0.x | ~18.7k | N/A | All tools loaded upfront |
V3.0.0 | ~0 | Platform-managed | Tools loaded on-demand |
npm run build # Compile TypeScript to JavaScript
npm run dev # Development mode with watch compilation
npm test # Run Jest test suite (60% coverage)
npm run test:coverage # Generate coverage report
npm run lint # ESLint with auto-fix
npm run format # Prettier code formattingJest with ESM support and TypeScript compilation
60% coverage across statements, branches, functions, lines
1136 tests covering core functionality, edge cases, error handling
Pre-commit hooks enforce code quality via Husky + lint-staged
Core Components:
src/index.ts — MCP server with tool registration and routing
src/tools/ — 29 tools organized by category (xcodebuild, simctl, idb, cache, workflows)
src/state/ — Multi-layer intelligent caching (simulator, project, response, build settings)
src/utils/ — Shared utilities (command execution, validation, error formatting)
src/types/ — TypeScript definitions for Xcode data structures
Cache Architecture:
Simulator Cache: 1-hour retention, usage tracking, performance metrics
Project Cache: Remembers successful build configurations per project
Build Settings Cache: Auto-discovers bundle IDs, deployment targets, capabilities
Response Cache: 30-minute retention for progressive disclosure
I appreciate contributions, but please note that this repo and my other public repos are far down in the priority queue of what I'm working on, so I'll be slow to review anything. Your best bet is really just to fork the repo and customise it to your own needs.
PR requirements:
Tests pass (npm test)
Coverage remains ≥60% (npm run test:coverage)
Code passes linting (npm run lint)
TypeScript compiles (npm run build)
See CLAUDE.md for detailed development guidelines and architecture documentation.
MIT License — See LICENSE for details.
XC-MCP: Production-grade Xcode automation for AI agents through progressive disclosure and accessibility-first workflows.
Quick assessment of accessibility tree richness - decide whether to use accessibility or screenshots.
Rapidly queries the accessibility tree and assesses data richness without returning full element details. Returns a quality score and recommendation (accessibility-ready or screenshot-fallback) in ~80ms with minimal token cost. Prevents agents from wasting tokens on expensive screenshots when accessibility data is sufficient.
udid (string): Target identifier - auto-detects if omitted
screenContext (string): Screen name for semantic tracking (e.g., "LoginScreen")
quality: "rich" | "moderate" | "minimal"
recommendation: "accessibility-ready" | "consider-screenshot"
elementCounts: Total elements, tappable elements, text fields, element types
queryTime: Query execution time in milliseconds
queryGuidance: Next steps based on quality assessment
const check = await accessibilityQualityCheckTool({
screenContext: 'LoginScreen'
});
if (check.quality === 'rich') {
// Use accessibility: idb-ui-describe
} else {
// Fall back to screenshot
}const assessment = await accessibilityQualityCheckTool({
udid: 'DEVICE-UDID'
});
// Workflow guided by quality3 tappable elements, OR
Text input fields detected
Recommendation: Use idb-ui-describe and accessibility-based navigation
2-3 tappable elements
Some custom UI that may not be recognized
Recommendation: Try accessibility tree first, fall back to screenshot if needed
≤1 element, OR
No tappable elements found
Recommendation: Take screenshot for visual analysis
Quick query: Calls idb ui describe-all (~80ms)
Assess richness: Counts tappable elements, text fields
Return score: Quality assessment + recommendation
No elements returned: Just the counts and guidance
accessibility-quality-check: ~80ms, 30 tokens
Full idb-ui-describe: ~120ms, 50 tokens
screenshot: ~2000ms, 170 tokens
idb-ui-describe: Full accessibility tree with element details
idb-ui-find-element: Search for specific element by name
screenshot: Visual fallback when accessibility insufficient
Returns quality assessment only (not full element tree)
Recommended as first step before choosing automation approach
Saves tokens by preventing unnecessary screenshots
Identifies when UI has minimal accessibility support
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| screenContext | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses that the tool returns only quality scores and counts, not full element details. It specifies execution time (~80ms), token cost (~30 tokens), and the three quality levels, providing complete behavioral transparency beyond the lack of annotations.
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 well-structured with headings, tables, and code examples, making it easy to parse. However, it is somewhat lengthy; a slightly more concise version could improve efficiency without losing value.
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?
Despite lacking an output schema, the description fully explains return values (quality, recommendation, elementCounts, queryTime, queryGuidance), how it works, and cost comparison. It is complete for the tool's complexity.
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 input schema has 0% description coverage, but the description provides clear meanings for both parameters: udid (target identifier, auto-detects if omitted) and screenContext (screen name for semantic tracking). Examples further illustrate usage.
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: 'Quick assessment of accessibility tree richness - decide whether to use accessibility or screenshots.' It specifies the verb (assess) and resource (accessibility tree richness) and distinguishes from sibling tools like idb-ui-describe and screenshot.
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 explicit guidance on when to use (as a first step before choosing an automation approach), when not to use, and alternatives. It includes cost comparisons, quality levels with recommendations, and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified cache management - get statistics, get configuration, set configuration, clear cache.
Single tool for cache management. Routes to specialized handlers while maintaining clean operation semantics.
Get cache statistics and metrics.
Example:
await cacheTool({ operation: 'get-stats' })Returns: Cache statistics including size, hit rates, and usage metrics.
Get cache configuration for specific cache type.
Parameters:
cacheType (string, optional): Cache type - 'simulator', 'project', 'response', or 'all'
Example:
await cacheTool({
operation: 'get-config',
cacheType: 'simulator'
})Returns: Current configuration including max age settings.
Set cache configuration.
Parameters:
cacheType (string): Cache type - 'simulator', 'project', 'response', or 'all'
maxAgeMs (number, optional): Maximum age in milliseconds
maxAgeMinutes (number, optional): Maximum age in minutes
maxAgeHours (number, optional): Maximum age in hours
Example:
await cacheTool({
operation: 'set-config',
cacheType: 'simulator',
maxAgeHours: 2
})Clear cache for specific type.
Parameters:
cacheType (string, optional): Cache type - 'simulator', 'project', 'response', or 'all'
Example:
await cacheTool({
operation: 'clear',
cacheType: 'simulator'
})simulator: Simulator list and state cache
project: Project configuration and build settings cache
response: Large response output cache for progressive disclosure
all: All caches (default when not specified)
list-cached-responses: View cached response IDs
xcodebuild-get-details: Retrieve cached build output
simctl-get-details: Retrieve cached simulator details
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| cacheType | No | ||
| maxAgeMs | No | ||
| maxAgeMinutes | No | ||
| maxAgeHours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly explains each operation's behavior, input/output, and cache types. It includes examples and return descriptions, though it lacks details on side effects (e.g., clearing cache) or error conditions.
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 well-organized with headings, sections, and examples. It is detailed but not overly verbose; however, some redundancy exists (e.g., cache types listed in two places).
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?
All four operations are fully documented with parameters, examples, and return descriptions. Related tools are mentioned for context. Despite the absence of output schema, the description adequately covers what to expect.
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?
With 0% schema description coverage, the description adds significant value by explaining each parameter, including the enum options for operation and cacheType, and the meaning of maxAgeMs/Minutes/Hours. Examples further clarify usage.
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 'Unified cache management' and enumerates all operations (get-stats, get-config, set-config, clear). It distinguishes from sibling tools like list-cached-responses by mentioning them as related tools, showing differentiation.
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?
Each operation is explained with examples and parameter details, providing clear context for when to use each. The 'Related Tools' section offers guidance on alternatives, though it could be more explicit about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified IDB app lifecycle management - install, uninstall, launch, terminate.
Single tool for IDB-based app management. Routes to specialized handlers while maintaining clean operation semantics.
Install iOS app via IDB.
Parameters:
appPath (string): Path to .app bundle
udid (string, optional): Target device UDID
Example:
await idbAppTool({
operation: 'install',
appPath: '/path/to/MyApp.app'
})Uninstall iOS app via IDB.
Parameters:
bundleId (string): App bundle ID
udid (string, optional): Target device UDID
Example:
await idbAppTool({
operation: 'uninstall',
bundleId: 'com.example.MyApp'
})Launch iOS app via IDB.
Parameters:
bundleId (string): App bundle ID
udid (string, optional): Target device UDID
arguments (string[], optional): Command-line arguments
environment (object, optional): Environment variables
streamOutput (boolean, optional): Stream app output
Example:
await idbAppTool({
operation: 'launch',
bundleId: 'com.example.MyApp',
arguments: ['--debug'],
streamOutput: true
})Terminate running iOS app via IDB.
Parameters:
bundleId (string): App bundle ID
udid (string, optional): Target device UDID
Example:
await idbAppTool({
operation: 'terminate',
bundleId: 'com.example.MyApp'
})idb-targets: List and manage IDB targets
idb-ui-tap, idb-ui-input, idb-ui-gesture: UI automation
simctl-app: Simctl-based app management
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| udid | No | ||
| bundleId | No | ||
| appPath | No | ||
| streamOutput | No | ||
| arguments | No | ||
| environment | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains each operation's parameters and provides examples, but lacks details on side effects, permissions, error states, or what happens on failure.
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 well-structured with headers, code blocks, and examples, but it is verbose. Some repetition could be reduced without losing clarity.
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 complexity (4 operations, 7 params), the description covers each operation's parameters and examples. However, it lacks any mention of return values or error handling, which would improve completeness.
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?
With 0% schema description coverage, the description adds significant value by documenting each operation's parameters and their meanings (e.g., appPath, bundleId, arguments, environment). Nested objects like 'environment' are explained clearly.
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 'Unified IDB app lifecycle management - install, uninstall, launch, terminate.' It specifies the verb and resource, and distinguishes from siblings like simctl-app explicitly mentioned in related 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 'Related Tools' section lists alternatives (e.g., simctl-app, idb-ui-*), providing implicit guidance on when to use this tool. However, it doesn't explicitly state when not to use it, which would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List installed applications - discover apps available for testing with bundle IDs and running status.
Enumerates all installed applications on iOS targets with structured metadata including bundle ID, app name, install type (system/user/internal), running status, debuggability, and architecture. Filters apps by install type or running status to focus on user apps or active processes. Parses IDB's pipe-separated output into structured JSON for easy programmatic access.
None - all parameters are optional
udid (string): Target identifier - auto-detects if omitted
filterType (string): Filter by install type ("system", "user", or "internal")
runningOnly (boolean): Show only currently running apps
Structured app list with summary counts (total, running, debuggable, by install type), separate arrays for running vs. installed apps, applied filter details, and actionable guidance for launching, terminating, installing, or debugging apps.
const result = await idbListAppsTool({
filterType: 'user'
});const running = await idbListAppsTool({ runningOnly: true });const all = await idbListAppsTool({
udid: 'DEVICE-UDID-123'
});idb-launch: Launch app by bundle ID discovered here
idb-terminate: Stop running app found in list
idb-install: Install new app to target
IDB outputs pipe-separated text, converted to structured JSON
Output format: bundle_id | app_name | install_type | arch | running | debuggable
Filter by install type to focus on user apps vs system apps
Running status helps identify active processes for UI automation
Debuggable status indicates if debugger can be attached
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| filterType | No | ||
| runningOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behaviors: enumerates all installed apps, provides structured metadata, converts pipe-separated output to JSON, and indicates auto-detection of UDID. Does not contradict any annotations.
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?
Structured with clear headings and front-loaded summary. Some redundancy (Returns repeats details from Overview) but each section adds value. Could be slightly more concise.
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 3 parameters, the description covers return format (summary counts, arrays), provides examples, and notes about IDB output format. Leaves no major gaps for an agent to use the tool correctly.
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 0%, but the description's Parameters section explains each parameter: udid (auto-detects), filterType (enum values listed), runningOnly (boolean for running apps). Adds meaning beyond the bare schema.
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 explicitly states 'List installed applications' and distinguishes it by mentioning 'discover apps available for testing with bundle IDs and running status.' Among siblings like idb-targets, simctl-list, and idb-launch, this tool uniquely focuses on enumerating installed apps.
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?
Provides guidance on filtering by install type or running status, and the Related Tools section suggests when to use this tool in conjunction with launching, terminating, or installing apps. However, lacks explicit when-not or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified IDB target management - discover, inspect, focus, and manage connections.
Single tool for IDB target discovery and connection management. Routes to specialized handlers while maintaining clean operation semantics.
List all available IDB targets.
Parameters:
state (string, optional): Filter by state - 'Booted' or 'Shutdown'
type (string, optional): Filter by type - 'device' or 'simulator'
Example:
await idbTargetsToolUnified({
operation: 'list',
state: 'Booted'
})Returns: List of targets with metadata, state, and type information.
Get detailed information about a specific target.
Parameters:
udid (string): Target UDID
Example:
await idbTargetsToolUnified({
operation: 'describe',
udid: 'ABC-123-DEF'
})Returns: Detailed target information including screen dimensions, device model, iOS version.
Focus simulator window for interactive testing.
Parameters:
udid (string): Simulator UDID
Example:
await idbTargetsToolUnified({
operation: 'focus',
udid: 'ABC-123-DEF'
})Establish IDB companion connection to target.
Parameters:
udid (string, optional): Target UDID - auto-detects if omitted
Example:
await idbTargetsToolUnified({
operation: 'connect',
udid: 'ABC-123-DEF'
})Notes: Establishes persistent gRPC connection for faster subsequent operations. Useful for warming up connections before automated testing.
Close IDB companion connection to target.
Parameters:
udid (string, optional): Target UDID
Example:
await idbTargetsToolUnified({
operation: 'disconnect',
udid: 'ABC-123-DEF'
})idb-app: App management on IDB targets
idb-ui-tap, idb-ui-input, idb-ui-gesture: UI automation on targets
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| udid | No | ||
| state | No | ||
| type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It explains behaviors for each operation: list returns a list, describe returns details, focus focuses a window, connect establishes a persistent connection, and disconnect closes it. Side effects like network usage are implied but not detailed, which is acceptable.
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 well-structured with headers, sections, and examples. It is somewhat lengthy but front-loads the overview and uses efficient formatting. The 'Related Tools' section is slightly extraneous but helpful.
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 multiple operations, no output schema, and zero schema description coverage, the description covers parameters and return types broadly (e.g., 'List of targets with metadata'). However, it lacks detailed return structure or error handling, leaving some gaps.
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 0%, so the description must add meaning. It documents each parameter per operation (e.g., state and type for list, udid for describe/focus/connect/disconnect) and includes examples, adding significant value beyond the raw schema.
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 it is for 'Unified IDB target management' and lists operations (discover, inspect, focus, manage connections). The 'Related Tools' section distinguishes it from siblings like idb-app and idb-ui-tap, making the purpose unambiguous.
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?
Each operation is explained with context (e.g., connect: 'Establishes persistent gRPC connection... Useful for warming up connections'). The related tools section provides separation, but explicit when-not-to-use is missing, though implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 Query UI accessibility tree - discover tappable elements and text fields for precise automation
Queries iOS accessibility tree to discover UI elements, their properties (type, label, enabled state), coordinates (frame, centerX, centerY), and accessibility identifiers. Returns full tree with progressive disclosure (summary + cache ID for full data), element-at-point queries for tap validation, and data quality assessment (rich/moderate/minimal) to guide automation strategy. Automatically parses NDJSON output to extract all elements (not just first), includes AXFrame coordinate parsing for precise tapping, and caches large outputs to prevent token overflow.
Progressive Filtering: Supports 4 filter levels for element discovery - start conservative with moderate filtering (default), escalate to permissive/none if minimal data found.
iOS Compatibility: Recognizes iOS-specific accessibility fields (role, role_description, AXLabel, AXFrame) in addition to standard fields.
Discover all tappable elements from accessibility tree - buttons, cells, links identified by JSON element objects
Get precise tap coordinates (centerX, centerY) for elements without needing screenshots
Assess data quality before choosing automation approach - rich data enables precise targeting, minimal data requires screenshots
Validate tap coordinates by querying elements at specific points before execution
Progressive disclosure prevents token overflow on complex UIs - get summary first, full tree on demand
Progressive filter escalation - start with moderate filtering, escalate to permissive/none if minimal data found
operation (string): "all" | "point"
x (number, required for point operation): X coordinate to query
y (number, required for point operation): Y coordinate to query
udid (string): Target identifier - auto-detects if omitted
screenContext (string): Screen name for context (e.g., "LoginScreen")
purposeDescription (string): Query purpose (e.g., "Find tappable button")
filterLevel (string): "strict" | "moderate" | "permissive" | "none" (default: "moderate")
strict: Only obvious interactive elements via type field (original behavior)
moderate: Include iOS roles (role, role_description) - DEFAULT, fixes iOS button detection
permissive: Any element with role/type/label information
none: Return everything (debugging)
For "all": UI tree summary with element counts (total, tappable, text fields), data quality assessment (rich/moderate/minimal), top 20 interactive elements preview with centerX/centerY coordinates, uiTreeId for full tree retrieval, current filter level, and guidance on automation strategy including suggestions to escalate filter level if minimal data found.
For "point": Element details at coordinates including type, label, value, identifier, frame coordinates (x, y, centerX, centerY), enabled state, and tappability.
const result = await idbUiDescribeTool({
operation: 'all',
screenContext: 'LoginScreen',
purposeDescription: 'Find email and password fields'
});
// Result includes elements with centerX, centerY for direct tapping// 1. Start with default (moderate)
let result = await idbUiDescribeTool({ operation: 'all' });
// 2. If minimal data, try permissive
if (result.summary.dataQuality === 'minimal') {
result = await idbUiDescribeTool({
operation: 'all',
filterLevel: 'permissive'
});
}
// 3. If still minimal, try none (return everything)
if (result.summary.dataQuality === 'minimal') {
result = await idbUiDescribeTool({
operation: 'all',
filterLevel: 'none'
});
}
// 4. If STILL minimal, fall back to screenshots
if (result.summary.dataQuality === 'minimal') {
// Use screenshot-based approach
}const element = await idbUiDescribeTool({
operation: 'point',
x: 200,
y: 400
});
// Element includes frame coordinates if availableidb-ui-tap: Tap discovered elements using centerX/centerY coordinates
screenshot: Capture screenshot for visual element identification
idb-ui-find-element: Semantic element search by label/identifier
accessibility-quality-check: Quick assessment before choosing approach
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| operation | Yes | ||
| x | No | ||
| y | No | ||
| screenContext | No | ||
| purposeDescription | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly explains behavior: progressive disclosure with caching, automatic NDJSON parsing, filter levels, and iOS-specific field handling. It also covers data quality assessment and performance considerations (token overflow prevention).
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 comprehensive and well-structured with headings, bullet points, and examples. Though lengthy, each section adds value and is front-loaded with a clear summary. Minor verbosity could be trimmed but it's well-organized.
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 6 parameters and lack of output schema/annotations, the description provides complete guidance. It covers return values, filter levels, examples, and integration with sibling tools. The progressive disclosure and strategy patterns ensure effective agent usage.
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?
With 0% schema coverage, the description adds extensive meaning for all 6 parameters. It explains operation enum values, x/y coordinates for point operations, auto-detection of udid, and filterLevel with detailed explanations. Examples further clarify usage.
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 it queries the iOS accessibility tree to discover UI elements, their properties, and coordinates. It distinguishes from sibling tools like idb-ui-tap (tapping) and idb-ui-find-element (semantic search) by focusing on discovery and data quality assessment.
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?
Explicitly describes when to use: discover tappable elements, get precise coordinates, assess data quality, validate tap coordinates. Provides progressive filter escalation and mentions alternatives (e.g., screenshots for minimal data). Also references related tools for further actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find UI elements by semantic search in accessibility tree - no screenshots needed.
Queries the accessibility tree and searches for elements matching a label or identifier. Returns matching elements with tap-ready coordinates (centerX, centerY), enabling agents to find specific UI controls without visual analysis. Fast semantic search replaces screenshot-based visual scanning for complex UIs.
query (string): Search term to match against element labels or identifiers
udid (string): Target identifier - auto-detects if omitted
Array of matching elements with:
Type, label, identifier
Tap-ready coordinates (centerX, centerY)
Full frame boundaries (x, y, width, height)
Returns empty array if no matches found.
const result = await idbUiFindElementTool({
query: 'login'
});const emailField = await idbUiFindElementTool({
query: 'email',
udid: 'DEVICE-UDID'
});const search = await idbUiFindElementTool({
query: 'submit'
});Query accessibility tree: Calls idb ui describe-all (~80ms)
Filter by query: Searches element labels and identifiers (case-insensitive partial match)
Return coordinates: Provides tap-ready centerX/centerY for direct use with idb-ui-tap
accessibility-quality-check: Quick assessment of accessibility data richness
idb-ui-describe: Full accessibility tree with all element details
idb-ui-tap: Tap elements using coordinates
screenshot: Visual fallback if accessibility insufficient
Uses case-insensitive partial matching ("log" matches "Login")
Returns all matching elements (filter in agent logic if needed)
Only returns elements with valid frame coordinates
Much faster than visual analysis (~80ms vs 2000ms for screenshot)
5-6x cheaper token cost (~40 tokens vs ~170 for screenshot)
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| query | Yes |
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 discloses key behaviors: case-insensitive partial matching, returns all matches, only elements with valid coordinates, and performance metrics (~80ms, 5-6x cheaper tokens). It also explains internal workflow (calls idb ui describe-all). This is comprehensive and transparent.
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 well-structured with clear sections (Overview, Parameters, Returns, Examples, How It Works, Related Tools, Notes). It is front-loaded with the core purpose. While somewhat lengthy, each section provides valuable information and 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?
Despite no output schema, the description fully explains the return format (array with type, label, identifier, coordinates, frame boundaries) and covers the empty array case. It also gives usage context, performance trade-offs, and related tools. The description is complete for an agent to invoke correctly.
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 input schema has no descriptions (0% coverage), so the description adds essential meaning. It explains query as a search term for labels/identifiers and udid as an optional target identifier with auto-detection. Examples illustrate usage. However, it does not specify constraints like allowed characters or format, which would be helpful.
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 finds UI elements via semantic search in the accessibility tree and returns tap-ready coordinates. It distinguishes itself from siblings like screenshot (visual fallback) and idb-ui-describe (full accessibility tree), establishing a unique role.
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 (fast semantic search replacing screenshot analysis for complex UIs) and lists related tools with their purposes (e.g., accessibility-quality-check to assess data richness, idb-ui-tap for tapping). It clearly guides selection but does not explicitly state when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
👆 Perform gestures and hardware button presses - swipes, scrolls, and device controls for navigation
Executes swipe gestures (directional or custom paths) and hardware button presses on iOS targets. Supports standard swipe directions (up, down, left, right) with automatic screen-relative path calculation using configurable profiles (flick, swipe, drag), custom swipe paths with precise start/end coordinates, and hardware button simulation (HOME, LOCK, SIRI, SCREENSHOT, APP_SWITCH). Automatically validates velocity to ensure iOS recognizes gestures as swipes (>6000 px/sec). Validates coordinates against device bounds and provides semantic action tracking.
Automate scroll and navigation gestures - swipe to reveal content, dismiss modals, page through carousels
Use optimized swipe profiles for different UIs - flick for fast page changes, swipe for standard scrolling, drag for slow interactions
Test hardware button interactions without physical device access - home button, lock, app switching
Execute precise custom swipe paths for complex gesture-based UIs (drawing, map navigation)
Track gesture-based test scenarios with semantic metadata (actionName, expectedOutcome)
operation (string): "swipe" | "button"
direction (string): "up" | "down" | "left" | "right" - auto-calculates screen-relative path
profile (string, default: "standard"): "standard" | "flick" | "gentle" - gesture profile
startX, startY, endX, endY (numbers): Precise POINT coordinates for custom swipe path
duration (number, default: 200): Swipe duration in MILLISECONDS (e.g., 200 for 200ms) - uses profile default if omitted
buttonType (string): "HOME" | "LOCK" | "SIDE_BUTTON" | "APPLE_PAY" | "SIRI" | "SCREENSHOT" | "APP_SWITCH"
udid (string): Target identifier - auto-detects if omitted
actionName (string): Semantic action name (e.g., "Scroll to Bottom")
expectedOutcome (string): Expected result (e.g., "Reveal footer content")
standard: Default balance (75% distance, 200ms, 1475 points/sec) - perfect for general navigation
flick: Fast page changes (85% distance, 120ms, 2775 points/sec) - use for carousel/rapid navigation
gentle: Slow scrolling (50% distance, 300ms, 653 points/sec) - reliable but near-minimum threshold
All coordinates in POINT space (393×852 for iPhone 16 Pro), NOT pixel space. All profiles tested and verified working on iOS 18.5 home screen.
{"operation": "swipe", "direction": "up", "profile": "standard", "actionName": "Scroll Down"}{"operation": "swipe", "direction": "down", "profile": "standard", "actionName": "Scroll Up"}{"operation": "swipe", "direction": "left", "profile": "standard", "actionName": "Go to Next Page"}{"operation": "swipe", "direction": "right", "profile": "standard", "actionName": "Go to Previous Page"}{"operation": "swipe", "direction": "left", "profile": "flick", "duration": 120, "actionName": "Fast Swipe to Next"}{"operation": "swipe", "direction": "up", "profile": "gentle", "duration": 300, "actionName": "Slow Scroll Down"}{"operation": "swipe", "startX": 196, "startY": 600, "endX": 196, "endY": 200, "duration": 200, "actionName": "Custom Scroll"}{"operation": "button", "buttonType": "HOME", "actionName": "Background App"}{"operation": "button", "buttonType": "LOCK", "actionName": "Lock Device"}{"operation": "button", "buttonType": "SIDE_BUTTON", "actionName": "Trigger Side Button Action"}{"operation": "button", "buttonType": "SIRI", "actionName": "Activate Siri"}{"operation": "button", "buttonType": "SCREENSHOT", "actionName": "Capture Screenshot"}{"operation": "button", "buttonType": "APP_SWITCH", "actionName": "Show App Switcher"}Gesture execution status with operation details (direction/button, path coordinates for swipes), duration, velocity info, gesture context metadata, error details if failed, and verification guidance.
const result = await idbUiGestureTool({
operation: 'swipe',
direction: 'up',
actionName: 'Scroll to Bottom',
expectedOutcome: 'Reveal footer content'
});await idbUiGestureTool({
operation: 'swipe',
direction: 'left',
profile: 'flick',
actionName: 'Go to Next Page'
});await idbUiGestureTool({ operation: 'button', buttonType: 'HOME' });idb-ui-tap: For precise element tapping
idb-ui-describe: Find element coordinates
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| operation | Yes | ||
| direction | No | ||
| startX | No | ||
| startY | No | ||
| endX | No | ||
| endY | No | ||
| duration | No | Swipe duration in milliseconds (e.g., 200 for 200ms, default: 200ms) | |
| buttonType | No | ||
| actionName | No | ||
| expectedOutcome | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behaviors: velocity validation (>6000 px/sec), coordinate bound checking, profile parameterization with empirically tested metrics, and semantic action tracking. No contradictions with annotations exist.
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 well-structured with headings and bullet points, but overly verbose. Profile details are repeated in the 'Swipe Profiles' section and again in the 'Why you'd use it' list. Some example JSON is redundant (e.g., multiple swipe directions). Could be trimmed without losing clarity.
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 11 parameters, 1 required, no output schema, and no annotations, the description provides near-complete context: parameter details, JSON examples for every operation/button, return value summary, and empirical profile data. Minimal gaps (e.g., exact return format could be more structured).
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 only 9% (only 'duration' has a description). The description compensates comprehensively: explains operation values, direction semantics, profile defaults/behavior, coordinate space (point vs pixel), buttonType enumeration, and optional parameters (actionName, expectedOutcome). It adds units and example values beyond schema.
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 starts with a clear verb ('Perform gestures and hardware button presses') and specifies resources ('swipes, scrolls, and device controls for navigation'). It distinguishes itself from sibling tools by explicitly listing related tools (idb-ui-tap, idb-ui-describe) with brief differentiators.
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 'Why you'd use it' section outlines specific scenarios (automate scroll, test hardware buttons, custom paths). The 'Related Tools' section references alternatives, though it does not explicitly state when not to use this tool or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⌨️ Input text and keyboard commands - automated text entry and special key presses for form automation
Sends text input and keyboard commands to focused elements on iOS targets. Types text strings into active text fields, presses special keys (home, return, delete, arrows), and executes key sequences for complex input workflows. Automatically redacts sensitive data (passwords) in responses and provides semantic field context tracking for test documentation.
Automate form filling without manual keyboard interaction - login flows, search, data entry
Execute keyboard shortcuts and navigation (tab, return, arrows) for multi-field workflows
Safely handle sensitive data with automatic redaction in tool responses and logs
Track input operations with semantic metadata (actionName, fieldContext, expectedOutcome)
operation (string): "text" | "key" | "key-sequence"
text (string, required for text operation): String to type into focused field
key (string, required for key operation): Special key name (home, return, delete, tab, arrows, etc.)
keySequence (string[], required for key-sequence operation): Array of key names to press in order
udid (string): Target identifier - auto-detects if omitted
actionName (string): Semantic action name (e.g., "Enter Email")
fieldContext (string): Field name for context (e.g., "Email TextField")
expectedOutcome (string): Expected result (e.g., "Email field populated")
isSensitive (boolean): Mark as sensitive to redact from output
Input execution status with operation details (redacted if sensitive), duration, input context metadata for test tracking, error details if failed, and troubleshooting guidance specific to text vs. key operations.
const result = await idbUiInputTool({
operation: 'text',
text: 'user@example.com',
actionName: 'Enter Email',
fieldContext: 'Email TextField'
});await idbUiInputTool({ operation: 'key', key: 'return' });idb-ui-tap: Tap to focus text fields before typing
idb-ui-describe: Find text field coordinates
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| operation | Yes | ||
| text | No | ||
| key | No | ||
| keySequence | No | ||
| actionName | No | ||
| fieldContext | No | ||
| expectedOutcome | No | ||
| isSensitive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior fully. It mentions automatic redaction of sensitive data and metadata tracking, but does not explain failure modes (e.g., when no element is focused), side effects, or prerequisites like focus.
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 well-structured with clear sections, headings, emojis, and examples. It is front-loaded with the core purpose. However, it is slightly verbose (repeats redaction info) and could be tightened.
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 has 9 parameters and no output schema or annotations, the description covers behavior, parameters, examples, and related tools adequately. It lacks a detailed return type specification but summarizes the output format sufficiently.
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 provides detailed meanings for each parameter beyond the schema, e.g., 'text: String to type into focused field', 'key: Special key name', and explains the purpose of optional parameters like actionName and fieldContext. This compensates for the 0% schema description coverage.
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 opens with 'Input text and keyboard commands - automated text entry and special key presses for form automation', providing a specific verb and resource. It distinguishes itself from siblings like idb-ui-tap (focusing) and idb-ui-describe (finding coordinates) via the 'Related Tools' section.
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 'Why you'd use it' section clearly lists use cases (form filling, keyboard shortcuts, sensitive data handling) and mentions related tools for alternative actions. However, it lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🎯 Tap at coordinates on iOS screen - core UI automation primitive with screenshot coordinate transformation
Sends precise tap events to iOS targets at specified screen coordinates with automatic coordinate transformation from screenshot space to device space. Supports single tap, double tap, and long press gestures. Validates coordinates against device screen bounds and provides semantic action tracking for test documentation. Works on both simulators and physical devices over USB/WiFi.
Automate UI interactions from screenshot analysis - tap elements identified visually
Transform screenshot coordinates automatically when screenshots are resized for token efficiency
Validate tap coordinates against device bounds before execution to prevent out-of-range errors
Track test scenarios with semantic metadata (actionName, expectedOutcome, testScenario, step)
x (number): X coordinate (device coords or screenshot coords with applyScreenshotScale)
y (number): Y coordinate (device coords or screenshot coords with applyScreenshotScale)
udid (string): Target identifier - auto-detects if omitted
numberOfTaps (number, default: 1): Number of taps (set 2 for double-tap)
duration (number): Long press duration in milliseconds
applyScreenshotScale (boolean): Transform screenshot coords to device coords
screenshotScaleX (number): Scale factor for X axis from screenshot-inline
screenshotScaleY (number): Scale factor for Y axis from screenshot-inline
actionName (string): Semantic action name (e.g., "Login Button Tap")
screenContext (string): Screen name for context (e.g., "LoginScreen")
expectedOutcome (string): Expected result (e.g., "Navigate to HomeScreen")
testScenario (string): Test scenario name (e.g., "Happy Path Login")
step (number): Step number in test workflow
Tap execution status with transformed coordinates, input coordinate details (if transformed), action context metadata for test tracking, error details if failed, and verification guidance.
const result = await idbUiTapTool({
x: 150, y: 300,
applyScreenshotScale: true,
screenshotScaleX: 2.0, screenshotScaleY: 2.0,
actionName: "Login Button Tap",
expectedOutcome: "Navigate to HomeScreen"
});idb-ui-describe: Discover tappable elements and their coordinates
screenshot: Capture screenshot to identify tap targets
idb-ui-gesture: For swipes and hardware buttons
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| x | Yes | ||
| y | Yes | ||
| numberOfTaps | No | ||
| duration | No | ||
| applyScreenshotScale | No | ||
| screenshotScaleX | No | ||
| screenshotScaleY | No | ||
| actionName | No | ||
| screenContext | No | ||
| expectedOutcome | No | ||
| testScenario | No | ||
| step | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It explains coordinate transformation, validation, support for single/double/long press, and working on simulators/devices. It mentions error handling and verification guidance in returns. However, it does not mention potential side effects (e.g., navigation changes) or failure modes beyond 'error 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 well-structured with headings, bullet lists, and an example. It is front-loaded with a summary. While somewhat lengthy, every section adds value (parameters, returns, examples, related tools). Minor redundancy in the 'What it does' vs. 'Parameters' sections could be tightened.
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 has 13 parameters, no output schema, and multiple siblings, the description thoroughly covers purpose, usage context, parameter details, return information, and related tools. It also provides an actionable example, making it complete for an agent to correctly invoke the tool.
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?
Input schema has 0% description coverage, so the description fully compensates. It explains each parameter's purpose (e.g., applyScreenshotScale for coordinate transformation), defaults (numberOfTaps=1), and provides a usage example. This is critical for an agent to use the tool correctly.
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 specifies the tool's action ('Tap at coordinates on iOS screen') and resource ('iOS screen') with specific gesture types. It distinguishes itself from sibling tools like idb-ui-describe (for discovering elements) and idb-ui-gesture (for swipes), providing a clear unique role.
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 states when to use this tool (e.g., automating UI interactions from screenshot analysis, transforming coordinates, validating bounds, tracking scenarios). It implicitly suggests alternatives by listing related tools (idb-ui-describe, screenshot, idb-ui-gesture) and their purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified cache persistence management - enable, disable, check status.
Single tool for persistence configuration. Routes to specialized handlers while maintaining clean operation semantics.
Enable cache persistence to disk.
Parameters:
cacheDir (string, optional): Custom cache directory path
Example:
await persistenceTool({
operation: 'enable',
cacheDir: '/path/to/cache'
})Notes: Persists cache data across sessions. Useful for long-running projects or CI environments.
Disable cache persistence.
Parameters:
clearData (boolean, optional): Clear existing persistent data on disable
Example:
await persistenceTool({
operation: 'disable',
clearData: true
})Check persistence status.
Parameters:
includeStorageInfo (boolean, optional): Include storage usage details
Example:
await persistenceTool({
operation: 'status',
includeStorageInfo: true
})Returns: Persistence status (enabled/disabled), cache directory path, and optional storage information.
Enable persistence:
Long-running projects that benefit from cross-session cache
CI/CD environments where cache survives across builds
Development workflows where build history is valuable
Disable persistence:
Temporary debugging sessions
Testing with clean cache state
Clearing sensitive cached information
cache: Cache management and configuration
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| cacheDir | No | ||
| clearData | No | ||
| includeStorageInfo | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It details each operation's behavior and parameters, including that enable persists across sessions and disable can clear data. However, it lacks edge-case details like error handling, permissions, or idempotency, leaving gaps in transparency.
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 well-structured with sections but is somewhat verbose, repeating parameter details in both parameter lists and examples. While organized and front-loaded, it could be more concise without losing essential information.
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 operations, parameters, examples, and usage guidance. It references a related tool. However, it misses edge cases like error handling, permission requirements, or concurrency behavior, leaving some gaps for a management tool of this complexity.
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 0%, so the description must compensate. It adds meaning to all four parameters: cacheDir (custom directory), clearData (clear on disable), includeStorageInfo (storage usage details), and operation (enum values explained). Examples further clarify usage.
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 it is for cache persistence management with three specific operations: enable, disable, and status. It uses precise verbs and explicitly distinguishes itself from the related sibling tool 'cache' by noting it handles persistence configuration.
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 'When to Use' section provides explicit scenarios for enabling and disabling persistence, such as long-running projects and CI/CD. However, it does not explicitly state when not to use this tool or provide direct alternatives to the sibling tool 'cache', though it is referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
📖 Read The Manual - Progressive disclosure documentation system for all XC-MCP tools.
The rtfm tool provides access to comprehensive documentation for any of the 28 consolidated tools in this MCP server (v2.0+). This implements progressive disclosure: tool descriptions in the main list include full documentation (~18.7k tokens total for optimal agent understanding), while rtfm provides additional context and examples on demand.
Version History:
v1.x: 51 individual tools (~3,000-7,850 tokens depending on approach)
v2.0+: 28 consolidated tools (~18.7k tokens) - Comprehensive docs for optimal reasoning
Problem Solved: Tool documentation was originally stored in .md files within the src/ directory, which wouldn't be available in the published npm package (only dist/ is included in package.json "files" field).
Solution: Documentation is now embedded as TypeScript constants in each tool file, bundled into the compiled JavaScript, and accessible via this rtfm tool. This ensures documentation is always available, whether in development or in the published npm package.
toolName (optional): Name of specific tool to get documentation for
Examples: "xcodebuild-build", "simctl-device", "idb-app", "cache", "persistence"
Case-sensitive, must match exact tool registration name
categoryName (optional): Browse tools in a specific category
Examples: "build", "simulator", "app", "idb", "cache", "system"
Omit both parameters to see all categories
// Get documentation for consolidated simulator device tool
rtfm({ toolName: "simctl-device" })
// Get documentation for consolidated app management tool
rtfm({ toolName: "idb-app" })
// Browse all tools in the cache category
rtfm({ categoryName: "cache" })
// View all categories (no parameters)
rtfm({})Old individual tools are now consolidated into single tools with operation parameters:
simctl-boot, simctl-shutdown, simctl-create, simctl-delete, simctl-erase, simctl-clone, simctl-rename → simctl-device (operation enum)
simctl-install, simctl-uninstall, simctl-launch, simctl-terminate → simctl-app (operation enum)
idb-install, idb-uninstall, idb-launch, idb-terminate → idb-app (operation enum)
cache-get-stats, cache-get-config, cache-set-config, cache-clear → cache (operation enum)
persistence-enable, persistence-disable, persistence-status → persistence (operation enum)
idb-targets extended with idb-connect and idb-disconnect operations
For detailed examples and parameter specifications for each operation, use rtfm({ toolName: "simctl-device" }) etc.
Returns full markdown documentation including:
Tool description and purpose
Advantages over direct CLI usage
Parameter specifications with types and descriptions
Usage examples
Related tools
Common patterns and best practices
If toolName doesn't match any registered tool:
Error message with the attempted tool name
Suggestions based on partial matches (up to 5)
Complete list of all available tools
Example:
No documentation found for tool: "simctl-boo"
Did you mean one of these?
- simctl-boot
- simctl-shutdown
Available tools (28 total):
- xcodebuild-*
- simctl-*
- idb-*
- cache
- persistence
- rtfmXcodebuild Tools (7)
xcodebuild-version, xcodebuild-list, xcodebuild-showsdks
xcodebuild-build, xcodebuild-clean, xcodebuild-test
xcodebuild-get-details
Simctl Lifecycle Tools (6)
simctl-list, simctl-get-details, simctl-device (consolidated: boot/shutdown/create/delete/erase/clone/rename)
simctl-suggest, simctl-health-check
Simctl App Management Tools (3)
simctl-app (consolidated: install/uninstall/launch/terminate)
simctl-get-app-container, simctl-openurl
Simctl I/O & Testing Tools (7)
simctl-io, simctl-addmedia, simctl-privacy, simctl-push
simctl-pbcopy, simctl-status-bar, screenshot
IDB Tools (6)
idb-targets (extended: list/describe/focus/connect/disconnect)
idb-ui-tap, idb-ui-input, idb-ui-gesture, idb-ui-describe, idb-list-apps
idb-app (consolidated: install/uninstall/launch/terminate)
Cache Management Tools (2)
list-cached-responses
cache (consolidated: get-stats/get-config/set-config/clear)
Persistence Tools (1)
persistence (consolidated: enable/disable/status)
Documentation Tool (1)
rtfm (this tool!)
Each tool file exports a TOOL_NAME_DOCS constant containing its full documentation in markdown format:
// Example from src/tools/simctl/boot.ts
export const SIMCTL_BOOT_DOCS = `
# simctl-boot
...
`;All documentation constants are imported and mapped in src/tools/docs-registry.ts:
export const TOOL_DOCS: Record<string, string> = {
'simctl-boot': SIMCTL_BOOT_DOCS,
'xcodebuild-build': XCODEBUILD_BUILD_DOCS,
// ... 49 more tools
};Tool list shows concise descriptions (~300-400 tokens)
Each description ends with: "📖 Use rtfm with toolName: '{name}' for full documentation."
Full documentation accessed only when explicitly requested via rtfm
Prevents token overflow while maintaining comprehensive documentation access
✅ Self-contained: No external file dependencies ✅ NPM package ready: Documentation bundled in compiled JavaScript ✅ Token efficient: Progressive disclosure keeps default views concise ✅ Always available: Works in development and production ✅ Type-safe: TypeScript constants with proper typing ✅ Searchable: Fuzzy matching with suggestions for typos ✅ Comprehensive: Full documentation including examples and parameters
Explore available tools:
// Intentionally use invalid tool name to see full list
rtfm({ toolName: "help" })Learn specific tool usage:
rtfm({ toolName: "simctl-boot" })Understand tool parameters:
rtfm({ toolName: "xcodebuild-build" })Find related tools:
// Search by category prefix
rtfm({ toolName: "simctl" }) // Shows simctl-* suggestionslist-cached-responses: View cached progressive disclosure responses
cache-get-stats: Monitor cache performance and usage
Tool names are case-sensitive and must match exact registration names
Fuzzy matching provides suggestions for close matches
Documentation format is consistent markdown across all tools
Each tool's documentation is independently maintained in its source file
The TOOL_DOCS registry is automatically updated when tools are added/removed
| Name | Required | Description | Default |
|---|---|---|---|
| toolName | No | ||
| categoryName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It comprehensively details behavioral traits: returns markdown documentation, handles errors with fuzzy matching and suggestions, explains case sensitivity and parameter behavior, and describes the progressive disclosure pattern. This goes well beyond what annotations would provide.
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 structured with headings, bullet points, and code blocks, but it is excessively long, containing version history and implementation details that are not essential for an agent's immediate usage. While well-organized, it would benefit from trimming to focus on actionable information for the AI agent.
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 role as a documentation meta-tool, the description is extremely complete. It covers purpose, parameters, examples, error handling, migration paths, categories, implementation details, and benefits. No output schema exists, but the response format is clearly described. All necessary context for correct usage is provided.
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 input schema has 0% coverage for parameter descriptions. The description adds significant meaning by explaining the optional toolName and categoryName parameters, providing examples, and noting case sensitivity. It adds context on usage patterns but does not explicitly define behavior when both parameters are provided simultaneously, which would elevate it to a 5.
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 as providing access to comprehensive documentation for all XC-MCP tools. It explicitly distinguishes itself from sibling tools by being the meta-documentation tool, with a specific verb 'rtfm' and resource 'progressive disclosure documentation system'. It explains its role in the ecosystem, making it unmistakable what the tool does.
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 detailed guidance on when to use rtfm: to get full documentation beyond concise descriptions, explore categories, and see examples. It includes examples of usage and mentions that it supplements tool descriptions. However, it lacks explicit 'when not to use' guidance or alternatives, though the context implies it is supplementary. Score is 4 due to clear context but absence of explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture optimized screenshots with inline base64 encoding for direct MCP response transmission.
Captures simulator screenshots and returns them as base64-encoded images directly in the MCP response. Automatically optimizes images for token efficiency with tile-aligned resizing and WebP/JPEG compression. Includes interactive element detection and coordinate transforms.
udid (string, optional): Simulator UDID (auto-detects booted device if omitted)
size (string, optional): Screenshot size - half, full, quarter, thumb (default: half)
appName (string, optional): App name for semantic context
screenName (string, optional): Screen/view name for semantic context
state (string, optional): UI state for semantic context
enableCoordinateCaching (boolean, optional): Enable view fingerprinting for coordinate caching
Automatically optimizes screenshots for token efficiency:
half (default): 256×512 pixels, 1 tile, ~170 tokens (50% savings)
full: Native resolution, 2 tiles, ~340 tokens
quarter: 128×256 pixels, 1 tile, ~170 tokens
thumb: 128×128 pixels, 1 tile, ~170 tokens
Capture: Screenshot taken at native resolution
Resize: Automatically resized to tile-aligned dimensions (unless size='full')
Compress: Converted to WebP format at 60% quality (falls back to JPEG if unavailable)
Encode: Base64-encoded for inline MCP response transmission
Extract: Interactive elements detected from accessibility tree
Transform: Coordinate mapping provided for resized screenshots
MCP response with:
Base64-encoded optimized image (inline)
Screenshot optimization metadata (dimensions, tokens, savings)
Interactive elements with coordinates and properties
Coordinate transform for mapping screenshot to device coordinates
View fingerprint (if enableCoordinateCaching is true)
Semantic metadata (if provided)
await simctlScreenshotInlineTool({
udid: 'device-123'
})await simctlScreenshotInlineTool({
udid: 'device-123',
size: 'full'
})await simctlScreenshotInlineTool({
udid: 'device-123',
appName: 'MyApp',
screenName: 'LoginScreen',
state: 'Empty'
})await simctlScreenshotInlineTool({
udid: 'device-123',
enableCoordinateCaching: true
})Automatically extracts interactive elements from the accessibility tree:
Element type (Button, TextField, etc.)
Label and identifier
Bounds (x, y, width, height)
Tappability status
Limited to top 20 elements to avoid token overflow. Elements are filtered to only include those with bounds and hittable status.
When screenshots are resized (size ≠ 'full'), provides automatic coordinate transformation:
Use the coordinateTransformHelper field in the response with idb-ui-tap:
Identify element coordinates visually from the screenshot
Call idb-ui-tap with applyScreenshotScale: true plus scale factors
The tool automatically transforms screenshot coordinates to device coordinates
Example:
idb-ui-tap {
x: 256, // Screenshot coordinate
y: 512, // Screenshot coordinate
applyScreenshotScale: true,
screenshotScaleX: 1.67,
screenshotScaleY: 1.66
}
// Tool automatically calculates: deviceX = 256 * 1.67, deviceY = 512 * 1.66If not using automatic transformation:
scaleX: Multiply screenshot X coordinates by this to get device coordinates
scaleY: Multiply screenshot Y coordinates by this to get device coordinates
coordinateTransform.guidance: Human-readable instructions
Important: Most agents should use the automatic transformation via idb-ui-tap's applyScreenshotScale parameter. Manual calculation is provided for reference only.
When enableCoordinateCaching is true, computes a structural hash of the view:
elementStructureHash: SHA-256 hash of element hierarchy
cacheable: Whether view is stable enough to cache coordinates
elementCount: Number of elements in hierarchy
orientation: Device orientation
Excludes loading states, animations, and dynamic content from caching.
Visual analysis: LLM-based screenshot analysis with token optimization
UI automation: Detect interactive elements and get tap coordinates
Bug reporting: Capture and transmit screenshots inline
Test documentation: Screenshot with semantic context for test tracking
Coordinate caching: Store element coordinates for repeated interactions
Screenshots are optimized for minimal token usage:
Default (half): ~170 tokens (50% savings vs full)
Full: ~340 tokens (native resolution)
Quarter: ~170 tokens (75% savings vs full)
Thumb: ~170 tokens (smallest, for thumbnails)
Token counts are estimates based on Claude's image processing (170 tokens per 512×512 tile).
Auto-detection: If udid is omitted, uses the currently booted device
Temp files: Uses temp directory for processing, auto-cleans up
WebP fallback: Attempts WebP compression, falls back to JPEG if unavailable
Element extraction: Requires app to be running with accessibility enabled
Coordinate accuracy: Transform provides pixel-perfect coordinate mapping
Simulator not found: Validates simulator exists in cache
Simulator not booted: Indicates simulator must be booted first
Capture failure: Reports if screenshot capture fails
Optimization failure: Falls back to original if optimization fails
Element extraction: Gracefully degrades if accessibility is unavailable
Analyze visually: LLM processes inline image for visual analysis
Interact with elements: Use coordinates from interactiveElements
Tap elements: Apply coordinate transform if resized, then use simctl-tap
Query specific elements: Use simctl-query-ui for targeted element discovery
Cache coordinates: Store fingerprint for reuse on identical views
Feature | screenshot-inline | simctl-io |
Returns | Base64 inline | File path |
Optimization | Automatic | Manual |
Elements | Auto-detected | Not included |
Transform | Included | Included |
Use case | MCP responses | File storage |
Token usage | Optimized | Depends on size |
| Name | Required | Description | Default |
|---|---|---|---|
| udid | No | ||
| size | No | ||
| appName | No | ||
| screenName | No | ||
| state | No | ||
| enableCoordinateCaching | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the automatic optimization process (capture, resize, compress, encode, extract, transform), error handling, token efficiency, coordinate transformation, view fingerprinting, and temp file cleanup. With no annotations provided, the description fully compensates, making behavior highly transparent.
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 extensive but well-structured with clear headers, bullet points, tables, and examples. It is front-loaded with the core purpose. Minor repetition (e.g., token efficiency mentioned twice) but overall concise for the tool's complexity.
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 6 parameters, no output schema, and no annotations, the description covers all aspects: input, output (base64 image, metadata, elements, transform), error handling, use cases, comparison with siblings, and next steps. It is thorough and leaves no significant gaps.
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 0%, but the description explains all 6 parameters, including defaults (e.g., size defaults to 'half'), auto-detection for udid, and semantic context for appName, screenName, state. It also explains the size enum values in detail with pixel dimensions and token savings, adding significant meaning.
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 explicitly states 'Capture optimized screenshots with inline base64 encoding for direct MCP response transmission,' providing a specific verb and resource. It distinguishes itself from sibling tools like `simctl-io` through a comparison table, making the purpose clear and unique.
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 includes a comparison with `simctl-io` and a 'Common Use Cases' section, offering context for when to use this tool. However, it does not explicitly state when not to use it, though the alternatives are clear. This is strong guidance but not fully explicit on exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified iOS app lifecycle management - install, uninstall, launch, terminate.
Single tool for app management on simulators. Routes to specialized handlers while maintaining clean operation semantics.
Install iOS app to simulator.
Parameters:
udid (string): Simulator UDID (from simctl-list)
appPath (string): Path to .app bundle
Example:
await simctlAppTool({
operation: 'install',
udid: 'ABC-123-DEF',
appPath: '/path/to/MyApp.app'
})Uninstall iOS app from simulator.
Parameters:
udid (string): Simulator UDID
bundleId (string): App bundle ID (e.g., com.example.MyApp)
Example:
await simctlAppTool({
operation: 'uninstall',
udid: 'ABC-123-DEF',
bundleId: 'com.example.MyApp'
})Launch iOS app on simulator.
Parameters:
udid (string): Simulator UDID
bundleId (string): App bundle ID
arguments (string[], optional): Command-line arguments
environment (object, optional): Environment variables
Example:
await simctlAppTool({
operation: 'launch',
udid: 'ABC-123-DEF',
bundleId: 'com.example.MyApp',
arguments: ['--verbose'],
environment: { 'DEBUG': '1' }
})Terminate running iOS app on simulator.
Parameters:
udid (string): Simulator UDID
bundleId (string): App bundle ID
Example:
await simctlAppTool({
operation: 'terminate',
udid: 'ABC-123-DEF',
bundleId: 'com.example.MyApp'
})simctl-device: Boot/shutdown simulators
simctl-list: Discover simulators and their UDIDs
idb-app: IDB-based app management
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| udid | No | ||
| bundleId | No | ||
| appPath | No | ||
| arguments | No | ||
| environment | No |
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 describes operations but does not disclose behavioral traits such as whether operations are destructive (e.g., install/uninstall), error handling, or required permissions. For a lifecycle management tool, this is a significant gap.
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 well-structured with markdown sections, headers, and examples. It is somewhat verbose due to repeated examples, but each section adds value. It is front-loaded with purpose and overview.
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 complexity of multiple operations and optional parameters, the description is fairly complete. It explains each operation's parameters and provides examples. However, it does not specify return values (no output schema) or error handling, which slightly reduces completeness.
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 input schema has 0% description coverage, but the description provides detailed parameter explanations for each operation, including examples for arguments and environment. It adds significant meaning beyond the schema for all 6 parameters, including optionality and usage.
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 'Unified iOS app lifecycle management - install, uninstall, launch, terminate.' It specifies the resource (iOS app) and the verb (lifecycle management). The overview and related tools section distinguishes it from siblings like simctl-device and simctl-list.
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?
While the description lists related tools (simctl-device, simctl-list, idb-app), it does not explicitly state when to use this tool versus alternatives. It implies usage for app management but lacks clear 'when-to-use' and 'when-not-to-use' guidance. The structure implies context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified iOS simulator device management - boot, shutdown, create, delete, erase, clone, rename.
Single tool for all simulator device lifecycle operations. Routes to specialized handlers while maintaining clean operation semantics.
{"operation": "boot", "deviceId": "ABCD1234-5678-90EF-GHIJ-KLMNOPQRSTUV", "waitForBoot": true, "openGui": true}{"operation": "shutdown", "deviceId": "booted"}{"operation": "create", "name": "Test iPhone 16", "deviceType": "iPhone 16 Pro", "runtime": "iOS-18-0"}{"operation": "delete", "deviceId": "ABCD1234-5678-90EF-GHIJ-KLMNOPQRSTUV"}{"operation": "erase", "deviceId": "simulator-udid", "force": true}{"operation": "clone", "deviceId": "source-udid", "newName": "Snapshot Before Tests"}{"operation": "rename", "deviceId": "simulator-udid", "newName": "My Test Device"}Boot iOS simulator device with performance tracking.
Parameters:
deviceId (string): Device UDID, "booted" for current, or "all"
waitForBoot (boolean, default: true): Wait for device to finish booting
openGui (boolean, default: true): Open Simulator.app GUI
Example:
await simctlDeviceTool({ operation: 'boot', deviceId: 'ABC-123-DEF' })Shutdown iOS simulator devices.
Parameters:
deviceId (string): Device UDID, "booted" for all booted devices, or "all"
Example:
await simctlDeviceTool({ operation: 'shutdown', deviceId: 'ABC-123-DEF' })Create new iOS simulator device.
Parameters:
name (string): Display name for new simulator
deviceType (string): Device type (e.g., "iPhone 16 Pro")
runtime (string, optional): iOS version - defaults to latest
Example:
await simctlDeviceTool({ operation: 'create', name: 'TestDevice', deviceType: 'iPhone 16 Pro' })Permanently delete iOS simulator device.
Parameters:
deviceId (string): Device UDID to delete
Example:
await simctlDeviceTool({ operation: 'delete', deviceId: 'ABC-123-DEF' })Reset simulator to factory settings.
Parameters:
deviceId (string): Device UDID to erase
force (boolean, optional): Force erase even if booted
Example:
await simctlDeviceTool({ operation: 'erase', deviceId: 'ABC-123-DEF' })Clone simulator with complete state preservation.
Parameters:
deviceId (string): Source device UDID
newName (string): Name for cloned simulator
Example:
await simctlDeviceTool({ operation: 'clone', deviceId: 'ABC-123-DEF', newName: 'Snapshot' })Rename simulator device.
Parameters:
deviceId (string): Device UDID to rename
newName (string): New display name
Example:
await simctlDeviceTool({ operation: 'rename', deviceId: 'ABC-123-DEF', newName: 'Production' })simctl-list: Discover simulators and their UDIDs
simctl-app: Install and launch apps on devices
simctl-io: Take screenshots and record videos
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| deviceId | No | ||
| waitForBoot | No | ||
| openGui | No | ||
| name | No | ||
| deviceType | No | ||
| runtime | No | ||
| force | No | ||
| newName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains each operation's behavior (e.g., 'Permanently delete', 'Reset simulator to factory settings', 'clone with complete state preservation'). Missing details on side effects like GUI behavior after boot, but overall adequate.
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 well-structured with sections, tables, and code blocks, making it easy to parse. It is slightly redundant, repeating operation details in both example and per-operation sections, but remains clear and organized.
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 complexity (multiple operations, many parameters) and lack of output schema, the description thoroughly covers each operation, its parameters, and provides examples. Related tools are listed, providing sufficient context for an agent to invoke correctly.
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 0%, but the description compensates with per-operation parameter explanations, including defaults and valid values (e.g., deviceId 'booted' or 'all'). The examples provide concrete usage, enhancing understanding.
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 it's a unified tool for iOS simulator device lifecycle operations, listing specific actions (boot, shutdown, create, delete, erase, clone, rename). It distinguishes itself from sibling tools like simctl-list and simctl-app by focusing on device management.
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 an overview and includes a 'Related Tools' section, suggesting when to use alternate tools (e.g., simctl-list for discovery, simctl-io for screenshots). However, it lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Access iOS app file system containers for inspection and debugging.
Retrieves the file system path to an app's container directories on a simulator, enabling direct access to app bundle, data directories, and shared group containers for debugging and testing.
Debug data access: Inspect app Documents and Library folders
File inspection: View database files, preferences, and cached data
Testing validation: Confirm app writes data to correct locations
Container types: Access bundle (app binary), data (Documents/Library), and group (shared) containers
udid (string, required): Simulator UDID (from simctl-list)
bundleId (string, required): App bundle ID (e.g., com.example.MyApp)
containerType (string, optional): Container type - bundle, data, or group (default: data)
bundle: App binary and resources (read-only)
data: App's Documents and Library directories (read-write)
group: Shared containers for app groups (read-write)
JSON response with:
Container path for file system access
Container type information
Guidance for accessing and inspecting files
Simulator state and validation
await simctlGetAppContainerTool({
udid: 'ABC-123-DEF',
bundleId: 'com.example.MyApp'
})await simctlGetAppContainerTool({
udid: 'ABC-123-DEF',
bundleId: 'com.example.MyApp',
containerType: 'bundle'
})Debugging data persistence: Access app's Documents folder to inspect saved files
Database inspection: View SQLite database files and validate schema
Preferences debugging: Check UserDefaults plist files
Cache validation: Verify cached data is stored correctly
Bundle inspection: Access app binary and embedded resources
App not installed: Returns error if app is not installed on simulator
Invalid bundle ID: Validates bundle ID format (must contain '.')
Simulator not found: Validates simulator exists in cache
Container access failure: Reports if container cannot be accessed
View files: cd "<container-path>" && ls -la
Open in Finder: open "<container-path>/Documents"
Find files: find "<container-path>" -type f | head -20
Inspect specific file: cat "<container-path>/Documents/data.json"
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | ||
| bundleId | Yes | ||
| containerType | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description thoroughly covers behavior: container type access (read-only vs read-write), error handling, return structure, and next steps. It discloses all relevant behavioral traits.
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?
Well-structured with clear sections, examples, and bullet points. Slightly redundant between 'Why you'd use it' and 'Common Use Cases', but every sentence adds value and it 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?
Given no output schema and no annotations, the description is remarkably complete: covers purpose, all parameters, container types, error handling, examples, and next steps. Leaves no significant gaps.
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?
Input schema has 0% coverage, but the description adds full meaning for each parameter: udid source, bundleId format/example, containerType enum with explanations. This goes well beyond the bare schema.
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 explicitly states it retrieves file system path to app container directories on a simulator. It is a specific verb-resource combination and is distinct from siblings like simctl-list and idb-list-apps.
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?
Includes 'Why you'd use it' and 'Common Use Cases' sections that clearly define appropriate scenarios. Lacks explicit 'when not to use' or direct alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 Get detailed simulator information from cached list results - Progressive disclosure for devices.
Retrieves on-demand access to full simulator and runtime lists that were cached during simctl-list execution. Implements progressive disclosure pattern: initial simctl-list responses return concise summaries to prevent token overflow, while this tool allows drilling down into full device lists, filtered by device type or runtime when needed.
• Access full device lists without cluttering initial responses • Filter to specific device types (iPhone, iPad, etc.) • Filter to specific runtime versions • Get only available (booted) devices or all devices • Paginate results to manage token consumption
cacheId (string): Cache ID from simctl-list response
detailType (string): Type of details to retrieve
"full-list": Complete device and runtime information
"devices-only": Just device information
"runtimes-only": Just available runtimes
"available-only": Only booted devices
deviceType (string): Filter by device type (iPhone, iPad, etc.)
runtime (string): Filter by iOS runtime version
maxDevices (number): Maximum number of devices to return (default: 20)
Tool execution results with detailed simulator information
Complete device lists with full state and capabilities
Available devices and compatible runtimes
simctl-list: List available simulators and runtimes
xcodebuild-get-details: Get build or test details
Tool is auto-registered with MCP server
Requires valid cache ID from recent simctl-list
Cache IDs expire after 1 hour
Use for discovering available devices and runtimes
| Name | Required | Description | Default |
|---|---|---|---|
| cacheId | Yes | ||
| detailType | Yes | ||
| deviceType | No | ||
| runtime | No | ||
| maxDevices | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses caching, cache ID expiration (1 hour), auto-registration, and return types. It lacks mention of permissions but is otherwise thorough for a read-only 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 well-structured with sections (advantages, parameters, returns, related tools, notes) but is somewhat verbose. Every sentence adds value, but some redundancy could be trimmed.
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, the description explains return values (full device lists, state, capabilities). It covers usage pattern, caching, filtering, and related tools, leaving no obvious gaps for an agent.
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 0%, so the description fully explains all 5 parameters: cacheId required, detailType with enum values, deviceType, runtime, and maxDevices with default. Each parameter's purpose and usage are clearly described.
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 retrieves detailed simulator information from cached list results and implements progressive disclosure. This distinguishes it from sibling tools like simctl-list which returns concise summaries.
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 this tool (after simctl-list) and provides advantages like filtering and pagination. It lists related tools but does not explicitly state when not to use or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive iOS simulator environment health check.
Performs a complete diagnostic check of your iOS development environment, validating Xcode tools, simulators, runtimes, and disk space. Returns actionable recommendations for any issues found. Checks 6 critical areas in seconds: Xcode Command Line Tools, simctl availability, available simulators, booted simulators, available runtimes, and disk space.
None - performs complete environment check automatically.
Health report with pass/fail status for each check, specific guidance for failures, summary of passed/failed checks, and overall healthy status indicator.
await simctlHealthCheckTool();// Validate environment before running test suite
const health = await simctlHealthCheckTool();
if (!health.healthy) {
console.error('Environment issues detected');
}simctl-list: See available simulators after health check passes
simctl-create: Create simulators if none found
simctl-suggest: Get intelligent simulator recommendations
Checks 6 critical areas: Xcode tools, simctl, simulators, booted devices, runtimes, disk space
Provides specific solutions for each failed check
Validates entire toolchain in seconds
Warns if disk usage over 80% (simulators require significant space)
Perfect for troubleshooting when operations fail unexpectedly
Use before CI/CD pipeline execution to ensure environment health
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully discloses the tool's behavior: it checks 6 areas, returns pass/fail status and actionable recommendations, warns about disk usage over 80%, and validates the entire toolchain in seconds.
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 well-structured with headings, examples, and notes, but it is somewhat lengthy. However, each section adds value and the markdown formatting aids readability.
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?
The description is complete: it explains the purpose, what is checked, the output format, and provides usage examples. With no output schema, the description adequately covers what the agent can expect.
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 input schema has 0 parameters, so the baseline is 4. The description confirms no parameters are needed and explains that the tool performs a complete environment check automatically.
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 that the tool performs a 'comprehensive iOS simulator environment health check' and lists the 6 critical areas it checks. It distinguishes from sibling tools like simctl-list and simctl-create by focusing on diagnosis rather than listing or creating.
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 explicit guidance on when to use the tool, such as 'Perfect for troubleshooting when operations fail unexpectedly' and 'Use before CI/CD pipeline execution.' It also references related tools for follow-up actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture screenshots or record videos from iOS simulators with automatic optimization.
Captures simulator screen as optimized PNG images or records video with configurable codecs. Screenshots are automatically resized to tile-aligned dimensions for token efficiency and support semantic naming for AI agent reasoning.
udid (string, optional): Simulator UDID (auto-detects booted device if omitted)
operation (string, required): "screenshot" or "video"
outputPath (string, optional): Custom file path (auto-generated if omitted)
codec (string, optional): Video codec - h264, hevc, or prores (default: h264)
size (string, optional): Screenshot size - half, full, quarter, thumb (default: half)
appName (string, optional): App name for semantic naming
screenName (string, optional): Screen/view name for semantic naming
state (string, optional): UI state for semantic naming
Screenshots are automatically optimized for token efficiency:
half (default): 256×512 pixels, 1 tile, 170 tokens (50% savings)
full: Native resolution, 2 tiles, 340 tokens
quarter: 128×256 pixels, 1 tile, 170 tokens
thumb: 128×128 pixels, 1 tile, 170 tokens
Provide appName, screenName, and state to generate semantic filenames:
Format: {appName}_{screenName}_{state}_{date}.png
Example: MyApp_LoginScreen_Empty_2025-01-23.png
Enables AI agents to reason about screen context and track state progression
JSON response with:
File path and size information
Screenshot optimization metadata (dimensions, token count, savings)
Coordinate transform for mapping resized coordinates to device
Semantic metadata when provided
Guidance for viewing and using the capture
await simctlIoTool({
udid: 'device-123',
operation: 'screenshot'
})await simctlIoTool({
udid: 'device-123',
operation: 'screenshot',
size: 'full'
})await simctlIoTool({
udid: 'device-123',
operation: 'screenshot',
appName: 'MyApp',
screenName: 'LoginScreen',
state: 'Empty'
})await simctlIoTool({
udid: 'device-123',
operation: 'video',
codec: 'hevc'
})UI testing: Capture screenshots for visual regression testing
Bug reporting: Record videos demonstrating issues
Documentation: Create screenshots for app documentation
State tracking: Use semantic naming to track UI state progression
Token optimization: Use half/quarter sizes for LLM-based analysis
When screenshots are resized (size ≠ 'full'), a coordinate transform is provided:
scaleX: Multiply screenshot X coordinates by this to get device coordinates
scaleY: Multiply screenshot Y coordinates by this to get device coordinates
guidance: Human-readable scaling instructions
This enables accurate element tapping even with optimized screenshots.
Auto-detection: If udid is omitted, automatically uses the booted device
Temp files: Screenshots saved to /tmp unless custom path specified
Video recording: Press Ctrl+C to stop video recording
Simulator must be booted: Operations require running simulator
File permissions: Ensure output path is writable
Simulator not booted: Indicates simulator must be booted first
Simulator not found: Validates simulator exists in cache
File path errors: Reports if output path is not writable
Invalid operation: Validates operation is "screenshot" or "video"
View screenshot: open "<file-path>"
Copy to clipboard: pbcopy < "<file-path>"
Analyze with LLM: Use optimized size for token-efficient analysis
Use coordinates: Apply transform to map screenshot coords to device
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | ||
| operation | Yes | ||
| outputPath | No | ||
| size | No | ||
| codec | No | ||
| appName | No | ||
| screenName | No | ||
| state | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, but description thoroughly discloses auto-detection, temp file behavior, video stopping, prerequisite (booted simulator), file permissions, error handling, and return value structure. No contradictions with annotations.
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?
Well-organized with clear headings and subheadings. Every section adds value, from parameter details to examples and next steps. Despite length, it remains focused and front-loaded with core functionality.
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 complexity (8 parameters, no output schema), the description covers parameters, return values, error handling, coordinate transform, and optimization. No major gaps remain.
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?
Input schema has 0% description coverage, but the description fully explains each parameter's purpose, defaults, and constraints. Goes beyond schema by providing default values and semantic naming details.
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?
Clearly states it captures screenshots or records videos from iOS simulators with optimization. The verb 'capture' and resources 'screenshots' and 'videos' are specific. Implicitly distinguishes from sibling 'screenshot' by adding video and optimization details.
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?
Provides common use cases and important notes, but does not explicitly compare with sibling tools like 'screenshot'. However, the detailed feature description implies when to use this advanced tool over simpler alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List iOS simulators with intelligent progressive disclosure and caching.
Retrieves comprehensive simulator information including devices, runtimes, and device types. Returns concise summaries by default with cache IDs for progressive access to full details, preventing token overflow while maintaining complete functionality. Shows booted devices and recently used simulators first for faster workflows. Full output mode limits results to the most recently used devices for efficient browsing.
None - all parameters are optional
deviceType (string): Filter by device type (e.g., "iPhone", "iPad")
runtime (string): Filter by iOS runtime version (e.g., "17", "iOS 17.0")
availability (string, default: "available"): Filter by availability ("available", "unavailable", "all")
outputFormat (string, default: "json"): Output format ("json" or "text")
concise (boolean, default: true): Return concise summary with cache ID
max (number, default: 5): Maximum devices to return in full mode, sorted by lastUsed date (most recent first)
Concise mode: Summary with cacheId for detailed retrieval via simctl-get-details
Full mode: Limited device list (default 5 most recently used) with metadata showing total available and limit applied
When concise: false, the response includes:
devices: Top N devices across all runtimes, sorted by lastUsed date (most recent first)
metadata: Shows total devices in cache, devices returned, and limit applied
Devices without lastUsed date are placed at the end
Total limit applies across all runtimes, not per-runtime
await simctlListTool({});await simctlListTool({
deviceType: "iPhone",
concise: false
});await simctlListTool({
concise: false,
max: 10
});await simctlListTool({ runtime: "17.0" });simctl-get-details: Retrieve full device list using cache ID (bypasses max limit)
simctl-device: Boot, shutdown, or manage specific simulators
simctl-app: Install and launch apps on simulators
Prevents token overflow (raw output = 10k+ tokens) via concise summaries and device limiting
Default max=5 limits output to ~2.5k tokens (90% reduction from full 50-device list)
1-hour intelligent caching eliminates redundant queries
Shows booted devices and recently used simulators first in concise mode
Use simctl-get-details with cacheId for progressive access to full data (ignores max limit)
Device sorting: mostRecent (with lastUsed) → oldest (with lastUsed) → unknown (no lastUsed)
Smart filtering by device type, runtime, and availability
Essential: Use this instead of 'xcrun simctl list' for better performance
| Name | Required | Description | Default |
|---|---|---|---|
| deviceType | No | ||
| runtime | No | ||
| availability | No | available | |
| outputFormat | No | json | |
| concise | No | ||
| max | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It comprehensively discloses caching (1-hour), progressive disclosure (concise vs full mode), device limiting (default max=5), token overflow prevention, sorting (booted/recent first), and smart filtering. No contradictions.
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?
Description is well-structured with sections (Overview, Parameters, Returns, Device Limiting, Examples, Related Tools, Notes). It is thorough but some may consider it slightly verbose. However, every section adds distinct value.
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?
No output schema, but description explains return in both modes (concise: summary with cacheId; full: limited device list with metadata). Covers all parameters, caching, sorting, and limits. Completely addresses the tool's complexity.
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 has 0% description coverage, but description fully explains all 6 parameters: deviceType (filter by type), runtime (filter by version), availability (with enum and default), outputFormat (enum), concise (toggle summary), max (limit in full mode). Also explains device limiting behavior.
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 it lists iOS simulators with progressive disclosure and caching. It distinguishes from siblings like simctl-get-details (retrieve full details via cache ID), simctl-device (manage simulators), and simctl-app (app operations). The verb 'List' and resource 'iOS simulators' are specific.
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 explicit alternatives (simctl-get-details, simctl-device, simctl-app) and notes 'Essential: Use this instead of 'xcrun simctl list''. Examples show typical use cases. It lacks explicit when-not-to-use but provides good context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open URLs in a simulator, including web URLs, deep links, and special URL schemes.
Opens a URL in the simulator, which can be a web URL (http/https), custom app deep link (myapp://), or special URL scheme (mailto:, tel:, sms:). The system will route the URL to the appropriate app handler.
udid (string, required): Simulator UDID (from simctl-list)
url (string, required): URL to open (e.g., https://example.com or myapp://deeplink?id=123)
HTTP/HTTPS: Web URLs (opens in Safari)
Custom schemes: Deep links to your app (myapp://, yourapp://)
mailto: Email composition (opens Mail app)
tel: Phone dialer (opens Phone app on iPhone)
sms: SMS composition (opens Messages app)
facetime: FaceTime calls
maps: Apple Maps URLs
JSON response with:
URL open status
Detected URL scheme
Guidance for testing URL handling and deep links
await simctlOpenUrlTool({
udid: 'device-123',
url: 'https://example.com'
})await simctlOpenUrlTool({
udid: 'device-123',
url: 'myapp://open?id=123&action=view'
})await simctlOpenUrlTool({
udid: 'device-123',
url: 'mailto:test@example.com?subject=Hello'
})await simctlOpenUrlTool({
udid: 'device-123',
url: 'tel:+1234567890'
})Deep link testing: Verify app handles custom URL schemes correctly
Universal links: Test https:// URLs that open your app
Navigation testing: Confirm deep links navigate to correct screens
Parameter parsing: Verify URL parameters are parsed correctly
Fallback handling: Test behavior when no handler is registered
Simulator must be booted: URLs can only be opened on running simulators
Handler registration: Custom schemes require an app that handles them
URL encoding: Ensure URL parameters are properly encoded
Timing: Consider launching app first if testing immediate URL handling
No handler registered: Error if no app handles the URL scheme
Simulator not booted: Indicates simulator must be booted first
Invalid URL format: Validates URL has proper scheme and format
Simulator not found: Validates simulator exists in cache
Install app: simctl-install <udid> /path/to/App.app
Launch app: simctl-launch <udid> <bundleId>
Open deep link: simctl-openurl <udid> myapp://route?param=value
Take screenshot: simctl-io <udid> screenshot to verify navigation
Check logs: Monitor console for URL handling logs
Parameter variations: Test different query parameters
Invalid URLs: Verify error handling for malformed URLs
Background handling: Test URLs when app is backgrounded
Fresh launch: Test URLs when app is not running
State preservation: Verify app state is maintained after URL handling
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | ||
| url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It covers required simulator state, handler registration, URL encoding, error handling, and return format. No contradiction with annotations (none present).
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?
Well-structured with headings, examples, and bullet points. Front-loaded with summary. Some sections like 'Testing Strategies' are extensive but add value; overall efficient for the tool's complexity.
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?
Comprehensive: covers parameters, supported schemes, return values, examples, use cases, important notes, error handling, workflow, and testing strategies. No output schema, so description adequately explains return structure.
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 0%, but the description details each parameter: udid (Simulator UDID from simctl-list) and url (examples of supported URLs). This adds substantial meaning beyond the bare schema.
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 it opens URLs in a simulator, listing web, deep links, and special schemes. It distinguishes from sibling simctl-* tools by focusing on URL opening, with a dedicated workflow and examples.
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?
Provides context for when to use (deep link testing, etc.) and a workflow integrating with sibling tools. Does not explicitly state when not to use or compare to alternatives, but the purpose is unique among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send simulated push notifications to apps on simulators with test context tracking.
Sends push notifications with custom JSON payloads to apps, simulating remote notifications from APNS. Supports test tracking to verify push delivery and validate app behavior.
udid (string, required): Simulator UDID (from simctl-list)
bundleId (string, required): App bundle ID (e.g., com.example.MyApp)
payload (string, required): JSON payload with APS dictionary
testName (string, optional): Test name for tracking
expectedBehavior (string, optional): Expected app behavior description
Must be valid JSON with an "aps" dictionary:
{
"aps": {
"alert": "Notification text",
"badge": 1,
"sound": "default"
},
"custom": "Additional data"
}The testName and expectedBehavior parameters enable structured test tracking. This allows AI agents to verify push notification delivery and validate that app behavior matches expectations (e.g., navigation, UI updates, data refresh).
JSON response with:
Push delivery status
Delivery information (sent timestamp)
Test context with expected vs actual behavior
Guidance for verifying notification handling
await simctlPushTool({
udid: 'device-123',
bundleId: 'com.example.MyApp',
payload: JSON.stringify({
aps: { alert: 'Test notification' }
})
})await simctlPushTool({
udid: 'device-123',
bundleId: 'com.example.MyApp',
payload: JSON.stringify({
aps: {
alert: 'New message',
badge: 5,
sound: 'default'
}
})
})await simctlPushTool({
udid: 'device-123',
bundleId: 'com.example.MyApp',
payload: JSON.stringify({
aps: {
alert: {
title: 'New Order',
body: 'Order #1234 has been placed'
},
badge: 1
},
orderId: '1234',
action: 'view_order'
})
})await simctlPushTool({
udid: 'device-123',
bundleId: 'com.example.MyApp',
payload: JSON.stringify({
aps: { alert: 'Product available' },
productId: '567'
}),
testName: 'PushNotification_DeepLinkTest',
expectedBehavior: 'App navigates to ProductDetail view for product 567'
})Notification delivery testing: Verify app receives and displays notifications
Deep link navigation: Test notification taps navigate to correct screens
Badge updates: Verify badge count is updated correctly
Custom data handling: Test app processes custom payload data
Background behavior: Test app behavior when notification arrives in background
App must be running: Launch app first or test background notification handling
Payload validation: JSON must be valid and include "aps" dictionary
Immediate delivery: Notification is delivered immediately (no delay)
No user interaction: Notification appears automatically without tapping
Visual verification: Use simctl-io screenshot to confirm notification display
Invalid JSON: Error if payload is not valid JSON
App not running: May fail if app is not running (test background handling)
Simulator not booted: Indicates simulator must be booted first
Invalid bundle ID: Validates bundle ID format (must contain '.')
Launch app: simctl-launch <udid> <bundleId>
Send push: simctl-push <udid> <bundleId> <payload>
Take screenshot: simctl-io <udid> screenshot to verify delivery
Check navigation: Verify app navigated to expected screen
Validate data: Confirm app processed custom payload data
The testContext in the response includes:
testName: Identifier for this push notification test
expectedBehavior: What should happen when notification is received
actualBehavior: What actually happened (delivery success/failure)
passed: Whether test passed
This enables agents to track push notification tests and verify expected behavior.
Multiple notifications: Send sequential pushes to test badge accumulation
Different payload types: Test alert, sound-only, silent notifications
Content extensions: Test notification service extensions with custom content
Action buttons: Test notification actions and user responses
Notification grouping: Test thread-id for notification grouping
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | ||
| bundleId | Yes | ||
| payload | Yes | ||
| testName | No | ||
| expectedBehavior | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden of transparency. It discloses key behaviors: app must be running, notification delivered immediately, no user interaction needed, payload must be valid JSON with 'aps' dictionary. It also details error conditions (invalid JSON, app not running, etc.) and mentions test context tracking.
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 well-structured with clear sections and examples, but it is quite lengthy. Some sections like 'LLM Optimization' and repeated 'Test Context Tracking' could be condensed. The front-loading of purpose is good, but overall wordiness reduces conciseness.
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?
Despite having no output schema, the description fully covers the return value (JSON with delivery status, test context, and guidance). It also explains error handling, common use cases, and advanced testing strategies. For a tool with 5 parameters and significant complexity, the description is extremely 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?
The input schema has 0% description coverage, but the description thoroughly explains all five parameters: udid (from simctl-list), bundleId (app identifier), payload (JSON with aps dict), testName (for test tracking), expectedBehavior (expected app behavior). It provides multiple examples and payload format details, adding significant value beyond the schema.
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 it sends simulated push notifications to apps on simulators. It distinguishes itself from sibling tools like simctl-openurl (URL opening) and simctl-launch (app launch) by focusing on push notification simulation with test tracking. The verb-resource combination is precise.
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 comprehensive guidance on when to use the tool, including a testing workflow with sequential steps (launch app, send push, screenshot). It also lists common use cases (delivery testing, deep link navigation, etc.) and error handling scenarios. However, it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clean slate app installation - build, install, and launch with fresh simulator state.
Orchestrates a complete clean installation cycle in a single call:
Select Simulator - Auto-detect or use specified device
Shutdown - Ensure simulator is stopped
Erase (optional) - Wipe all simulator data
Boot - Start fresh simulator
Build - Compile the Xcode project
Install - Install the built app
Launch - Start the app
This workflow keeps intermediate results internal, reducing agent context usage by ~70% compared to calling each tool manually.
projectPath (string): Path to .xcodeproj or .xcworkspace
scheme (string): Build scheme name
simulatorUdid (string): Target simulator - auto-detected if omitted
eraseSimulator (boolean): Wipe simulator data before install (default: false)
configuration ("Debug" | "Release"): Build configuration (default: Debug)
launchArguments (string[]): App launch arguments
environmentVariables (Record<string, string>): App environment variables
Consolidated result with:
success: Overall workflow success
project: Build configuration details
simulator: Target simulator info
app: Installed app details (bundleId, path, launched)
totalDuration: Total workflow time
guidance: Next steps
{
"projectPath": "/path/to/MyApp.xcodeproj",
"scheme": "MyApp"
}Auto-selects simulator, builds, installs, and launches.
{
"projectPath": "/path/to/MyApp.xcworkspace",
"scheme": "MyApp",
"eraseSimulator": true,
"configuration": "Debug"
}Erases all simulator data for truly fresh state.
{
"projectPath": "/path/to/MyApp.xcodeproj",
"scheme": "MyApp",
"simulatorUdid": "ABC123-DEF456",
"launchArguments": ["-UITesting", "-ResetState"],
"environmentVariables": {"DEBUG_MODE": "1"}
}Targets specific simulator with custom launch configuration.
Manual approach: 6-7 tool calls × ~100 tokens each = ~600+ tokens in responses
Workflow approach: 1 call with consolidated response = ~150 tokens
Build logs not exposed (only success/failure)
Intermediate states summarized
Only actionable outcome returned
Shutdown ensures clean starting point
Optional erase for truly fresh state
Proper boot sequencing
workflow-tap-element: UI interaction after install
xcodebuild-build: Direct build (used internally)
simctl-device: Direct simulator control (used internally)
simctl-app: Direct app management (used internally)
Shutdown failures are non-fatal (simulator may already be off)
Auto-suggests best simulator based on project requirements
Build artifacts are located automatically
Bundle ID is discovered from build settings
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | Path to .xcodeproj or .xcworkspace | |
| scheme | Yes | Build scheme name | |
| simulatorUdid | No | Target simulator | |
| eraseSimulator | No | Wipe simulator data | |
| configuration | No | Debug | |
| launchArguments | No | ||
| environmentVariables | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears transparency burden. It details the 7-step orchestration, side effects (shutdown, optional erase, boot), and behaviors like handling shutdown failures as non-fatal. It also mentions that intermediate results are internal, which goes beyond basic operational description.
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 well-structured with overview, parameters, return values, examples, and rationale. It is somewhat long but each section serves a purpose. Minor redundancy exists (e.g., repeating step sequence in overview and later), but overall it is efficiently organized.
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 7 parameters, no output schema, and moderate schema coverage, the description compensates fully. It describes the return object structure, provides three examples covering different scenarios, and explains the workflow's advantages. This makes the tool understandable and actionable without relying on external schema details.
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 57% (4/7 parameters described). The description adds meaning via examples and parameter details (e.g., auto-detection for simulatorUdid, default values like false for eraseSimulator). It provides context beyond schema, though not all parameters get equal depth.
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 it performs a 'clean slate app installation' with a specific process sequence, and distinguishes itself from siblings like workflow-tap-element (UI interaction) and xcodebuild-build (direct build) via the 'Related Tools' section.
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 'Why Use This Workflow?' section explicitly compares token efficiency and context reduction vs manual calls, and 'Related Tools' lists alternatives for different tasks (e.g., UI interaction after install). This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-level semantic UI interaction - find and tap elements by name without coordinate hunting.
Orchestrates accessibility-first UI automation in a single call:
Check Accessibility - Assess UI richness for automation approach
Find Element - Semantic search by label/identifier
Tap Element - Execute tap at discovered coordinates
Input Text (optional) - Type into tapped field
Verify Result (optional) - Screenshot for confirmation
This workflow keeps intermediate results internal, reducing agent context usage by ~80% compared to calling each tool manually.
elementQuery (string): Search term for element (e.g., "Login", "Submit", "Email")
Case-insensitive partial matching ("log" matches "Login")
inputText (string): Text to type after tapping (for text fields)
verifyResult (boolean): Take screenshot after action (default: false)
udid (string): Target device - auto-detected if omitted
screenContext (string): Screen name for tracking (e.g., "LoginScreen")
Consolidated result with:
success: Overall workflow success
tappedElement: Found element details (type, label, coordinates)
inputText: Text entry status (if requested)
verified: Screenshot status (if requested)
accessibilityQuality: UI richness assessment
totalDuration: Total workflow time
guidance: Next steps
{"elementQuery": "Login"}Finds and taps the Login button.
{
"elementQuery": "Email",
"inputText": "user@example.com",
"screenContext": "LoginScreen"
}Finds email field, taps it, enters text.
{
"elementQuery": "Submit",
"verifyResult": true,
"screenContext": "SignupForm"
}Taps Submit button and captures verification screenshot.
Manual approach: 4-5 tool calls × ~50 tokens each = ~200+ tokens in responses
Workflow approach: 1 call with consolidated response = ~80 tokens
Intermediate accessibility data not exposed
Element search results summarized
Only actionable outcome returned
Graceful degradation on partial failures
Helpful guidance when element not found
Clear troubleshooting steps
idb-ui-find-element: Direct element search (used internally)
idb-ui-tap: Direct tap (used internally)
accessibility-quality-check: Direct quality check (used internally)
workflow-fresh-install: Clean app installation workflow
Falls back gracefully if accessibility is minimal
Non-fatal errors (input, screenshot) don't fail the workflow
Element matching uses partial, case-insensitive search
Small delay between tap and input for keyboard appearance
| Name | Required | Description | Default |
|---|---|---|---|
| elementQuery | Yes | Search term for element (e.g., "Login", "Submit") | |
| inputText | No | Text to type after tapping | |
| verifyResult | No | Take screenshot after action | |
| udid | No | Target device | |
| screenContext | No | Screen name for tracking |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses internal steps, fallback behavior, non-fatal error handling, and delays. Since annotations are absent, this fully covers behavioral traits without contradiction.
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?
Well-structured with sections, examples, and bullet points, though slightly verbose. Every part earns its place, but could be tightened without losing clarity.
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?
Fully documents return values and provides guidance for a complex workflow with no output schema. Covers all necessary context for 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?
Adds value beyond schema: case-insensitive partial matching, default values, and detailed examples. Schema coverage is 100%, so baseline 3; extra examples push to 4.
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 it's a high-level workflow for tapping UI elements by name, distinguishing it from sibling tools like idb-ui-tap and idb-ui-find-element.
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?
Includes a dedicated 'Why Use This Workflow?' section explaining token efficiency and reduced context pollution, and lists related tools. Explicit guidance on when to use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚡ Build Xcode projects with intelligent defaults and performance tracking
Builds Xcode projects and workspaces with advanced learning capabilities that remember successful configurations and suggest optimal simulators per project. Uses progressive disclosure to provide concise summaries by default, with full build logs available on demand. Tracks build performance metrics (duration, errors, warnings) and learns from successful builds to improve future build suggestions.
Automatic smart defaults: remembers which simulator and config worked last time
Progressive disclosure: concise summaries prevent token overflow, full logs on demand
Performance tracking: measures build times and provides optimization insights
Structured errors: clear error messages instead of raw CLI stderr
projectPath (string): Path to .xcodeproj or .xcworkspace file
scheme (string): Build scheme name (use xcodebuild-list to discover)
configuration (string, default: 'Debug'): Build configuration (Debug/Release, defaults to cached or "Debug")
destination (string): Build destination (e.g., "platform=iOS Simulator,id=")
sdk (string): SDK to build against (e.g., "iphonesimulator", "iphoneos")
derivedDataPath (string): Custom derived data path for build artifacts
Structured JSON response with buildId (for progressive disclosure), success status, build summary (errors, warnings, duration), and intelligence metadata showing which smart defaults were applied. Use xcodebuild-get-details with buildId to retrieve full logs.
const result = await xcodebuildBuildTool({
projectPath: "/path/to/MyApp.xcodeproj",
scheme: "MyApp"
});const release = await xcodebuildBuildTool({
projectPath: "/path/to/MyApp.xcworkspace",
scheme: "MyApp",
configuration: "Release",
destination: "platform=iOS Simulator,id=ABC-123"
});xcodebuild-test: Run tests after building
xcodebuild-clean: Clean build artifacts
xcodebuild-get-details: Get full build logs (use with buildId)
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | ||
| scheme | Yes | ||
| configuration | No | Debug | |
| destination | No | ||
| sdk | No | ||
| derivedDataPath | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It explains that the tool remembers successful configurations, uses progressive disclosure, tracks build metrics, and returns structured JSON with a buildId for log retrieval. It does not mention any destructive side effects or permissions, but for a build tool, the described behavior is transparent enough.
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 well-structured with markdown headings, emojis, and sections for purpose, benefits, parameters, returns, examples, and related tools. It is detailed but efficient, with every section providing necessary information. No redundant content.
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?
Despite no output schema, the description thoroughly covers input parameters, return value structure, and how to retrieve full logs via another tool. It also mentions related tools and provides examples. For a complex tool with 6 parameters, this description is highly 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?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, defaults, and examples. Required parameters (projectPath, scheme) are clearly described, and optional parameters (configuration, destination, etc.) include usage context and defaults. The examples demonstrate typical use cases.
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 builds Xcode projects with intelligent defaults and performance tracking. It differentiates itself from siblings like xcodebuild-test, xcodebuild-clean, and xcodebuild-get-details by highlighting its learning capabilities and progressive disclosure.
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 'Why you'd use it' section lists key benefits (smart defaults, progressive disclosure, performance tracking, structured errors) and the 'Related Tools' section provides alternatives for different use cases (e.g., testing, cleaning, logs). While it doesn't explicitly state when not to use this tool, the guidance is sufficiently clear for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚡ Clean build artifacts with validation and structured output
Removes build artifacts and intermediate files for an Xcode project or workspace. Pre-validates that the project exists and Xcode is properly installed before executing, providing clear error messages if something is misconfigured. Returns structured JSON responses with execution status, duration, and any errors encountered during the clean operation.
Resolve build issues by removing stale or corrupted build artifacts
Free up disk space occupied by intermediate build files
Ensure clean builds from scratch without cached compilation results
Get structured feedback with execution time and success status
projectPath (string): Path to .xcodeproj or .xcworkspace file
scheme (string): Build scheme name to clean
configuration (string): Build configuration to clean (e.g., "Debug", "Release")
Structured JSON response containing success status, command executed, execution duration, output messages, and exit code. Includes both stdout and stderr for comprehensive debugging. Operation typically completes in under 3 minutes.
const result = await xcodebuildCleanTool({
projectPath: "/path/to/MyApp.xcodeproj",
scheme: "MyApp"
});const cleanRelease = await xcodebuildCleanTool({
projectPath: "/path/to/MyApp.xcworkspace",
scheme: "MyApp",
configuration: "Release"
});xcodebuild-build: Build after cleaning
xcodebuild-list: Discover available schemes
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | ||
| scheme | Yes | ||
| configuration | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses pre-validation of project existence and Xcode installation, structured JSON output with success status, duration, errors, and typical execution time under 3 minutes. No contradictions.
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?
Well-structured with sections, emoji, and examples. Front-loaded with header and purpose. Slightly verbose (e.g., repeated 'structured JSON response') but clear and organized.
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 3 parameters, description covers purpose, parameters, output type, examples, pre-validation, and execution time. Lacks detailed output field list but sufficient for a clean operation.
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 has 0% description coverage, but description adds meaning: projectPath is path to .xcodeproj or .xcworkspace, scheme is build scheme name, configuration is optional with examples (Debug, Release). Examples illustrate usage. Not all parameters are fully detailed (e.g., configuration values), but sufficient.
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 removes build artifacts and intermediate files for Xcode projects. It distinguishes itself from siblings like xcodebuild-build (for building after cleaning) and xcodebuild-list (for discovering schemes), making its purpose unique and specific.
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?
Provides 'Why you'd use it' with concrete scenarios (resolve build issues, free up disk space, ensure clean builds). References related tools but does not explicitly state when not to use this tool (e.g., if you need to build instead of clean).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 Retrieve detailed build or test output from cached results - Progressive disclosure for logs.
Provides on-demand access to full build and test logs that were cached during xcodebuild-build or xcodebuild-test execution. Implements progressive disclosure pattern: initial build/test responses return concise summaries to prevent token overflow, while this tool allows drilling down into full logs, filtered errors, warnings, or metadata when needed for debugging.
• Access full build logs without cluttering initial responses • Filter to just errors or warnings for faster debugging • Retrieve exact command executed and exit code • Inspect build metadata and cache information
buildId (string): Cache ID from xcodebuild-build or xcodebuild-test response
detailType (string): Type of details to retrieve
"full-log": Complete stdout and stderr output
"errors-only": Lines containing errors or build failures
"warnings-only": Lines containing warnings
"summary": Build metadata and configuration used
"command": Exact xcodebuild command executed
"metadata": Cache info and output sizes
maxLines (number): Maximum lines to return (default: 100)
Tool execution results with requested build or test details
Full logs or filtered errors/warnings with line counts
Build metadata and execution information
xcodebuild-build: Build iOS projects (returns buildId)
xcodebuild-test: Run tests (returns testId)
simctl-get-details: Get simulator list details
Tool is auto-registered with MCP server
Requires valid cache ID from recent build/test
Cache IDs expire after 30 minutes
Use for debugging build failures and test issues
| Name | Required | Description | Default |
|---|---|---|---|
| buildId | Yes | ||
| detailType | Yes | ||
| maxLines | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description thoroughly discloses behavioral traits: it retrieves cached results, uses progressive disclosure to avoid token overflow, and notes cache ID expiration. It also mentions auto-registration with MCP server.
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 well-structured with headings, bullet points, and emojis. Every section adds necessary value without redundancy. It is appropriately sized for the tool's complexity.
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?
Despite no output schema, the description covers return values (tool execution results, filtered logs, metadata). It also includes notes on cache ID expiration and usage, making it complete for a tool with moderate complexity.
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 input schema provides minimal descriptions, but the description compensates with detailed explanations of each parameter, including the enum values for detailType and default value for maxLines. Schema description coverage is 0%, but the description adds full meaning.
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 retrieves detailed build/test output from cached results, implementing a progressive disclosure pattern for logs. It is distinct from sibling tools like xcodebuild-build and xcodebuild-test, which produce the initial summaries.
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 this tool (for debugging build failures/test issues) and mentions related tools and requirements (valid cache ID, 30-minute expiration). It also lists alternative tools in the 'Related Tools' section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚡ List project targets, schemes, and configurations with intelligent caching
Discovers and returns all available build targets, schemes, and configurations for an Xcode project or workspace. Uses 1-hour intelligent caching to remember results and avoid expensive re-runs of project discovery. Validates both Xcode installation and project path before execution to provide clear error messages if something is misconfigured.
Discover available schemes before building or testing (essential for automation)
Validate project structure and configuration
Get structured project metadata for CI/CD pipelines
Avoid expensive repeated queries with 1-hour caching
projectPath (string): Path to .xcodeproj or .xcworkspace file
outputFormat (string, default: 'json'): "json" or "text" output format
Structured JSON containing all targets, schemes, configurations, and project information. Consistent format across .xcodeproj and .xcworkspace project types. Results are cached for 1 hour to speed up subsequent queries.
const info = await xcodebuildListTool({
projectPath: "/path/to/MyApp.xcodeproj"
});const textInfo = await xcodebuildListTool({
projectPath: "/path/to/MyApp.xcworkspace",
outputFormat: "text"
});xcodebuild-build: Build discovered schemes
xcodebuild-test: Test discovered schemes
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | ||
| outputFormat | No | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides good behavioral context: it mentions 1-hour caching, validates Xcode installation and project path before execution, and gives clear error messages. It does not discuss any side effects or permissions.
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 well-structured with clear sections (What it does, Why you'd use it, Parameters, Returns, Examples, Related Tools). It uses markdown headings, code blocks, and bullet points. While a bit lengthy, every part adds value.
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?
The description explains return type (structured JSON), caching behavior, validation checks, and provides examples. For a read-only listing tool without an output schema, it covers all necessary information for an agent to use it correctly.
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 0%, but the description adds meaningful parameter details: projectPath is a path to .xcodeproj or .xcworkspace, outputFormat defaults to 'json' with enum values 'json' and 'text'. Examples reinforce usage. Minor lack: no explanation of text output format.
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 lists project targets, schemes, and configurations for Xcode projects. It distinguishes from siblings like xcodebuild-build and xcodebuild-test by focusing on discovery and metadata retrieval.
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 includes a 'Why you'd use it' section listing concrete use cases and mentions related tools for context. However, it does not explicitly state when not to use the tool or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚡ Run Xcode tests with intelligent defaults and progressive disclosure
Executes unit and UI tests for Xcode projects with advanced learning that remembers successful test configurations and suggests optimal simulators per project. Provides detailed test metrics (passed/failed/skipped) with progressive disclosure to prevent token overflow. Supports test filtering (-only-testing, -skip-testing), test plans, and test-without-building mode for faster iteration. Learns from successful test runs to improve future suggestions.
Automatic smart defaults: remembers which simulator and config worked for tests
Detailed test metrics: structured pass/fail/skip counts instead of raw output
Progressive disclosure: concise summaries with full logs available via testId
Test filtering: run specific tests or skip problematic ones with -only-testing/-skip-testing
projectPath (string): Path to .xcodeproj or .xcworkspace file
scheme (string): Test scheme name (use xcodebuild-list to discover)
configuration (string, default: 'Debug'): Build configuration (Debug/Release, defaults to cached or "Debug")
destination (string): Test destination (e.g., "platform=iOS Simulator,id=")
sdk (string): SDK to test against (e.g., "iphonesimulator")
derivedDataPath (string): Custom derived data path
testPlan (string): Test plan name to execute
onlyTesting (string[]): Array of test identifiers to run exclusively
skipTesting (string[]): Array of test identifiers to skip
testWithoutBuilding (boolean): Run tests without building (requires prior build)
Structured JSON with testId (for progressive disclosure), success status, test summary (total/passed/failed/skipped counts), failure details (first 3 failures), and cache metadata showing which smart defaults were applied. Use xcodebuild-get-details with testId for full logs.
const result = await xcodebuildTestTool({
projectPath: "/path/to/MyApp.xcodeproj",
scheme: "MyApp"
});const filtered = await xcodebuildTestTool({
projectPath: "/path/to/MyApp.xcworkspace",
scheme: "MyApp",
onlyTesting: ["MyAppTests/testLogin", "MyAppTests/testLogout"]
});const quick = await xcodebuildTestTool({
projectPath: "/path/to/MyApp.xcodeproj",
scheme: "MyApp",
testWithoutBuilding: true
});{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp"}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "testPlan": "IntegrationTests"}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "onlyTesting": ["MyAppTests/LoginTests", "MyAppTests/AuthTests/testLogin"]}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "skipTesting": ["MyAppTests/SlowTests", "MyAppUITests"]}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "testWithoutBuilding": true}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "destination": "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.0"}{"projectPath": "/path/to/MyApp.xcodeproj", "scheme": "MyApp", "configuration": "Release"}xcodebuild-build: Build before testing
xcodebuild-get-details: Get full test logs (use with testId)
simctl-list: See available test simulators
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | ||
| scheme | Yes | ||
| configuration | No | Debug | |
| destination | No | ||
| sdk | No | ||
| derivedDataPath | No | ||
| testPlan | No | ||
| onlyTesting | No | ||
| skipTesting | No | ||
| testWithoutBuilding | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses learning behavior (remembers configs), progressive disclosure (testId for logs), and test-without-building efficiency. Lacks mention of rate limits or error handling, but otherwise thorough.
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 long but well-structured with headings, bullet points, and examples. It is front-loaded with a summary. Every section adds value, though some details could be condensed for an AI agent.
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 complexity (10 params, no output schema, no annotations), the description is highly complete: covers purpose, usage, parameters, return values (progressive disclosure), examples, and related tools. Missing only minor error handling details.
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?
With 0% schema description coverage, the description compensates fully: it lists all 10 parameters with explanations, defaults, required status, and even cross-refers to sibling tools. Examples in JSON illustrate usage.
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 'Run Xcode tests' (verb+resource) and distinguishes itself from siblings like xcodebuild-build (build) and xcodebuild-get-details (get logs). It specifies unit and UI tests.
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 'Why you'd use it' section lists benefits (smart defaults, metrics, progressive disclosure, filtering) and the 'Related Tools' section provides alternatives. However, it does not explicitly state when not to use this tool (e.g., if only building), though it is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚡ Get Xcode and SDK version information with structured output
Retrieves comprehensive version information about your Xcode installation and available SDKs. Returns structured JSON data that's easy to parse and validate, eliminating the need to parse raw command-line output. Validates Xcode installation before execution to provide clear error messages if Xcode is not properly configured.
Validate environment before running builds or tests (CI/CD validation)
Check SDK availability for specific platform versions
Ensure consistent Xcode versions across team or build environments
Get structured version data for automated tooling and scripts
sdk (string): Query specific SDK version (e.g., "iphoneos", "iphonesimulator")
outputFormat (string, default: 'json'): "json" or "text" output format
Structured JSON response containing Xcode version, build number, and SDK information. Falls back gracefully to text format for older Xcode versions that don't support JSON output.
const result = await xcodebuildVersionTool({ outputFormat: "json" });const sdkInfo = await xcodebuildVersionTool({ sdk: "iphoneos" });xcodebuild-showsdks: Show all available SDKs
xcodebuild-list: List project information
| Name | Required | Description | Default |
|---|---|---|---|
| sdk | No | ||
| outputFormat | No | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses validation of Xcode installation and graceful fallback to text format for older versions. These are useful behavioral traits, though no side effects or destructive actions are expected.
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 well-organized with sections and examples, but slightly lengthy. Every sentence adds value, maintaining clarity without unnecessary verbosity.
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?
Despite no output schema, the description adequately explains the return value: structured JSON with version info and fallback to text. All necessary information for a version retrieval tool is covered.
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 0%, so description compensates. It explains both parameters: 'sdk' for querying specific SDKs and 'outputFormat' with default 'json' and enum values. Examples and fallback behavior add context beyond schema.
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 'Get Xcode and SDK version information' with a specific verb and resource. It distinguishes itself from sibling tools like xcodebuild-showsdks and xcodebuild-list by focusing on version retrieval.
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 'Why you'd use it' section provides clear use cases such as CI/CD validation and environment consistency. However, it does not explicitly state when not to use this tool or mention alternatives beyond related tools.
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.
v2.0.2xcodebuild-testv3.2.0xcodebuild-testv1.1.0accessibility-quality-checkcachecache-clearcache-get-configcache-get-statscache-set-configidb-appidb-list-appsidb-targetsidb-ui-describeidb-ui-find-elementidb-ui-gestureidb-ui-inputidb-ui-taplist-cached-responsespersistencepersistence-disablepersistence-enablepersistence-statusrtfmscreenshotsimctl-appsimctl-bootsimctl-devicesimctl-get-app-containersimctl-get-details6 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / cacheId / descriptionRemoved value: -"Cache ID from previous simctl-list call"Input schema / properties / detailType / descriptionRemoved value: -"Type of details to retrieve"Input schema / properties / deviceType / descriptionRemoved value: -"Filter by device type (iPhone, iPad, etc.)"Input schema / properties / maxDevices / descriptionRemoved value: -"Maximum number of devices to return"Input schema / properties / runtime / descriptionRemoved value: -"Filter by runtime version"simctl-health-checksimctl-iosimctl-list7 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / availability / descriptionRemoved value: -"Filter by device availability"Input schema / properties / concise / descriptionRemoved value: -"Return concise summary (true) or full list (false)"Input schema / properties / deviceType / descriptionRemoved value: -"Filter by device type (iPhone, iPad, Apple Watch, Apple TV)"Input schema / properties / maxAdded value: +{
+ "default": 5,
+ "type": "number"
+}Input schema / properties / outputFormat / descriptionRemoved value: -"Output format preference"Input schema / properties / runtime / descriptionRemoved value: -"Filter by iOS runtime version (e.g., \"17\", \"iOS 17.0\", \"16.4\")"simctl-openurlsimctl-pushsimctl-shutdownworkflow-fresh-installworkflow-tap-elementxcodebuild-build7 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / configuration / descriptionRemoved value: -"Build configuration (Debug, Release, etc.)"Input schema / properties / derivedDataPath / descriptionRemoved value: -"Custom derived data path"Input schema / properties / destination / descriptionRemoved value: -"Build destination. If not provided, uses intelligent defaults based on project history and available simulators."Input schema / properties / projectPath / descriptionRemoved value: -"Path to .xcodeproj or .xcworkspace file"Input schema / properties / scheme / descriptionRemoved value: -"Build scheme name"Input schema / properties / sdk / descriptionRemoved value: -"SDK to use for building (e.g., \"iphonesimulator\", \"iphoneos\")"xcodebuild-clean4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / configuration / descriptionRemoved value: -"Configuration to clean"Input schema / properties / projectPath / descriptionRemoved value: -"Path to .xcodeproj or .xcworkspace file"Input schema / properties / scheme / descriptionRemoved value: -"Scheme to clean"xcodebuild-get-details4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / buildId / descriptionRemoved value: -"Build ID from previous xcodebuild-build call"Input schema / properties / detailType / descriptionRemoved value: -"Type of details to retrieve"Input schema / properties / maxLines / descriptionRemoved value: -"Maximum number of lines to return for logs"xcodebuild-list3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / outputFormat / descriptionRemoved value: -"Output format preference"Input schema / properties / projectPath / descriptionRemoved value: -"Path to .xcodeproj or .xcworkspace file"xcodebuild-showsdksxcodebuild-testxcodebuild-version3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / outputFormat / descriptionRemoved value: -"Output format preference"Input schema / properties / sdk / descriptionRemoved value: -"Specific SDK to query (optional)"v1.0.0cache-clearcache-get-configcache-get-statscache-set-configlist-cached-responsespersistence-disablepersistence-enablepersistence-statussimctl-bootsimctl-get-detailssimctl-listsimctl-shutdownxcodebuild-buildxcodebuild-cleanxcodebuild-get-detailsxcodebuild-listxcodebuild-showsdksxcodebuild-versionScored across 30 tools
Tool purposes are mostly distinct but there is some overlap among UI automation tools (e.g., accessibility-quality-check vs idb-ui-describe, screenshot vs simctl-io). Descriptions are detailed, helping agents differentiate, but the sheer number of UI-related tools could cause confusion.
Most tools follow a prefix-action pattern (simctl-*, idb-*, xcodebuild-*, workflow-*), but there is inconsistency with tools like 'cache', 'persistence', 'rtfm', and 'screenshot' that lack a prefix. Overall, the naming is predictable and readable.
30 tools is on the high side for a well-scoped server. While many are consolidated via operation parameters (reducing atomic operations), the exported tool count feels heavy for an Xcode wrapper. It is borderline but still manageable.
The tool set covers the majority of iOS development workflows: build, test, simulator management, UI automation, caching, and workflow orchestration. Minor gaps exist (e.g., no direct code signing management), but overall it is highly comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Agent Token Budget MCP — hard per-session token + spend cap with signed budget-exhausted
Apple Developer Documentation with Semantic Search, RAG, and AI reranking for MCP clients
Remote MCP for Copilot CLI switch gate MCP, structured receipts, audit logs, and reviewer-ready evid
MCP-Native LLM Orchestration Agent
