Skip to content
Skills Library
AI & agents · Planning

api-design

/api-design

Use BEFORE adding any new tool, parameter, or endpoint to the Apple Mail MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.

Licence
MIT
Last repository change
07.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use BEFORE adding any new tool, parameter, or endpoint to the Apple Mail MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.

Original author description

Use BEFORE adding any new tool, parameter, or endpoint to the Apple Mail MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.

How it works

  1. Decision Tree: Use BEFORE Adding Any Tool
  2. Anti-Patterns (Never Do These)
  3. Response Format Rules
  4. Tool Naming Convention
  5. Adding a New Tool Checklist
Original SKILL.md headings · 87 lines, 403 words
SKILL.md preview
---
name: api-design
description: Use BEFORE adding any new tool, parameter, or endpoint to the Apple Mail MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.
---

# Apple Mail MCP API Design

The current API has 17 tools organized into 4 phases. Tool count should grow slowly and deliberately. Every new tool request must pass through the decision tree.

## Decision Tree: Use BEFORE Adding Any Tool

```
Can an existing tool handle this with current parameters?  (70% of cases: YES)
  |-- Searching with a new filter? -> Add parameter to search_messages()
  |-- Reading with different format? -> Add parameter to get_messages()
  |-- Sending/composing with new options? -> Extend create_draft() or update_draft()
  |
Can an existing tool handle this with a NEW parameter?  (20% of cases: YES)
  |-- Example: search by date range -> add date_from, date_to to search_messages()
  |-- Example: search flagged only -> add is_flagged to search_messages()
  |
Is this truly a distinct operation?  (10% of cases: MAYBE)
  |-- Different Mail.app object? (accounts, rules, smart mailboxes)
  |-- Different action type? (not CRUD on messages/mailboxes)
  |
If NO to all three: You might need a new tool. This is rare.
```

## Anti-Patterns (Never Do These)

### Field-Specific Tools
```python
# WRONG - creates tool sprawl
mark_as_flagged(message_id)
mark_as_unflagged(message_id)
mark_as_junk(message_id)

# RIGHT - one CRUD-style update tool with patch semantics
update_message(message_ids, read_status=True)
update_message(message_ids, flag_color="red")
update_message(message_ids, destination_mailbox="Archive", account="Gmail")
```

### Specialized Search Tools
```python
# WRONG - each filter becomes a tool
get_unread_messages()
get_flagged_messages()
get_messages_from_sender()

# RIGHT - parameters on existing search
search_messages(read_status="unread")
search_messages(is_flagged=True)
search_messages(sender_contains="user@example.com")
```

### Formatted Text Returns
```python
# WRONG - returns human-readable string
def list_mailboxes():
    return "Inbox (42 messages)\nSent (15 messages)"

# RIGHT - returns structured data
def list_mailboxes():
    return {"success": True, "mailboxes": [{"name": "Inbox", "count": 42}, ...]}
```

## Response Format Rules

1. **Always return `dict[str, Any]`** with `"success": bool`
2. **Errors include `"error"` (message) and `"error_type"` (category)**
3. **Never return formatted text strings** — return structured data
4. **Include context fields** — e.g., `"messages_found": 5` alongside the results

## Tool Naming Convention

- Verb + noun: `search_messages`, `create_draft`, `delete_messages`
- Plural when accepting lists: `delete_messages`, `get_messages`
- CRUD-style for multi-field mutation: `update_message(read_status, flag_color, destination_mailbox, ...)` over per-field verbs (`mark_as_read`, `flag_message`, `move_messages`). Patch semantics — unset fields are unchanged.

## Adding a New Tool Checklist

1. Verify it doesn't fit in an existing tool (run through decision tree above)
2. Write unit tests (mock AppleScript)
3. Write integration tests (real Mail.app)
4. Implement in `mail_connector.py`
5. Expose in `server.py`
6. Run `./scripts/check_client_server_parity.sh`
7. Update `docs/reference/TOOLS.md`
8. Add blind eval scenarios if tool has non-obvious parameters

Versions

RepositoryScoreLicence
This page · s-morgan-jeffries/apple-mail-fast-mcp100MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Database snapshot: 13.11.2026 · package version 8a97d6d1a60d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100build-mcp-server
    This skill should be used when the user asks to "build an MCP server", "create an MCP", "make an MCP integration", "wrap an API for Claude", "expose tools to Claude", "make an MCP app", or discusses building something with the Model Context Protocol. It is the entry point for…
  • 100mcp2cli
    Turn any MCP server, OpenAPI spec, or GraphQL endpoint into a CLI. Use this skill when the user wants to interact with an MCP server, OpenAPI/REST API, or GraphQL API via command line, discover available tools/endpoints, call API operations, or generate a new skill from an API.…
  • 100b2c-mcp-server
    Index and setup for the B2C Commerce MCP server, covering toolset selection, tool choice by task, and the skill catalog. Use to enable tools, pick the right tool, or find the skill that covers a B2C task.
  • 90tool-schema-designer
    This skill should be used when the user wants to "expose an API to Claude", "turn this endpoint / controller / OpenAPI spec into a tool", "write a tool definition", "design function calling schema", "Claude keeps calling the wrong tool", or is defining tools for the Claude API,…
  • 84audit
    Audit MCP server tool definitions against design quality criteria. Use when: 'audit MCP tools', 'check MCP tool descriptions', 'review MCP server quality', 'tool annotations', 'readOnlyHint missing', 'parameter descriptions missing', 'check the _meta annotations',…
  • 100mcp-tool
    Optimize the tool surface of an EXTERNAL MCP server — one the agent talks to but does not implement. Use when an agent wired to an MCP server mis-selects tools, fills arguments wrong, or is offered a noisy 40-tool set it mostly ignores. Covers MCP tool descriptions,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.