Bridge AI agents to the Zeph mobile app for notifications, decisions, content sharing, and cross-session coordination.
Send one-way push notifications with title, body, optional URL, priority, and target device (zeph_notify).
Copy text to the device clipboard (zeph_clipboard).
List, dismiss, or clear notifications (zeph_list, zeph_dismiss, zeph_dismiss_all).
Broadcast notifications to channel subscribers (zeph_broadcast).
Send files or generated text to the device (zeph_file).
Ask a blocking question with quick-reply buttons and/or free text, receiving answers and attachments (zeph_ask).
Rename the current agent session (zeph_session_rename).
Type plaintext messages into another agent session (zeph_agent_send).
Read connected devices and channels resources (zeph://devices, zeph://channels).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@zeph-to/mcp-server Send a notification that the build succeeded."
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.
Your agent calls zeph_ask; the question lands on your phone as buttons + a text field; your reply comes back into the same tool call and the agent keeps going.
Zeph's MCP server is the agent side of that round trip — plus one-way notifications, clipboard, files, and channel broadcasts, all over the Model Context Protocol. Works with Claude Code, Cursor, Windsurf, Gemini CLI, and any MCP client.
Part of the Zeph toolchain: @zeph-to/cli (installer, push CLI, tmux remote control) · zeph-to/plugin (Claude Code plugin bundling this server) · the Zeph app on your phone.
New here? docs.zeph.to walks the whole setup — one command on your machine, the app on your phone, and a restart. The reference below assumes that is already done.
The easiest way to set up for all agents at once:
npm install -g @zeph-to/cli
zeph installThis saves credentials to ~/.zeph/config.json and configures your agents automatically. The MCP server reads from this file — no env vars needed. Install globally so zeph cc (phone-driven sessions) works and hooks skip an npx cold-start; npx @zeph-to/cli install is a notifications-only alternative.
Add to ~/.claude/settings.json:
{
"mcpServers": {
"zeph": {
"command": "npx",
"args": ["-y", "@zeph-to/mcp-server"]
}
}
}No env block needed: credentials come from ~/.zeph/config.json (written
by zeph install). Add env vars only to override the file —
e.g. a second account:
"env": { "ZEPH_API_KEY": "ak_other_account" }{
"command": "npx",
"args": ["-y", "@zeph-to/mcp-server"]
}Related MCP server: agent-comm
Variable | Required | Description |
| Yes* | API key from Settings > API Keys |
| No | Hook ID (optional — only needed for |
| No | Target device ID (optional — only needed for |
| No | API base URL (default: |
| No | Deprecated. WebSocket endpoint for the hook-response fast path. |
| No | Set to |
| No | Override the session id attached to pushes (grouping in the app). Auto-detected from the newest Claude Code transcript when unset |
| No | Set to |
* If env vars are not set, the server reads from ~/.zeph/config.json (created by zeph install). Unresolved ${...} interpolations are also treated as unset.
Push titles are automatically prefixed with the project directory name — myapp · Build complete — so the phone feed stays scannable when several sessions push at once.
Send a one-way push notification. Supports optional URL (auto-switches to link type).
title: "Build complete"
body: "All 42 tests passed"
url: "https://github.com/org/repo/actions/runs/123" (optional)
priority: "low" | "normal" | "high" | "urgent"
targetDeviceId: "dev_..." (optional, overrides ZEPH_DEVICE_ID)Copy text to the user's device clipboard.
text: "npm install @zeph-to/mcp-server"
targetDeviceId: "dev_..." (optional)List recent push notifications.
limit: 5 (1-20, default: 5)
type: "note" (optional filter: note, link, file, clipboard, hook)Returns: { pushes: [...], total: 5, hasMore: true }
Mark a specific push as read.
pushId: "push_01HX..."Clear all notifications at once. No parameters.
Returns: { dismissed: 12, badge: 0 }
Send a notification to all subscribers of a channel.
channelId: "ch_..."
title: "Deploy complete"
body: "v2.1.0 is live"
url: "https://..." (optional)
priority: "normal"Send a file to the user's device. Either filePath (a file already on disk) or
content (text you generated) is required.
filePath: "/abs/path/screenshot.png" (images, PDFs, logs — anything on disk)
content: "{\"status\": \"ok\"}" (text only; requires fileName)
fileName: "report.json" (required with content; defaults to basename of filePath)
title: "Build Report" (optional, defaults to fileName)
targetDeviceId: "dev_..." (optional)Images are delivered with their real mime type and render inline on the device.
Never base64 a binary file into content — pass filePath and the server reads
the bytes off disk.
Returns: { pushId: "...", fileKey: "...", fileSize: 42, encrypted: true, delivery: "Sent via cloud" }
Always the cloud. A file an agent sends goes through Zeph, whatever network
the target is on, and the result says delivery: "Sent via cloud". The direct
hand-over of ADR-0013 belongs to the phone's share sheets, where a person picks
the route for a file they chose; an agent writing a report has no such consent
to read from, and a copy in the cloud is the one every device on the account
can open later.
Set a custom display name for the current agent session, shown in the Zeph app's Streams › Agents list. Lets an agent label what it's working on — "Prod deploy", "Auth refactor" — so parallel sessions are easy to tell apart on your phone. Renames the session this server runs in (resolved from the listener device id + tmux session name); the name persists until changed.
alias: "Prod deploy watcher" (1-60 chars)Returns: { renamed: true, session: "zeph-myapp", alias: "Prod deploy watcher" }, or { renamed: false, reason: "..." } when there's no active session to rename (not running inside a zeph listener tmux session).
Type a message into another agent session — Claude Code, Codex, pi, … on any of the user's machines — as if the user had sent it from their phone. It shows in that session's chat in the app, and, like any command from the phone, puts that session in remote mode.
target: "dev_listener_ab12cd34:zeph-api" session key <deviceId>:<tmuxName>, or a name/alias that names one session
message: "Build is green on main — rebase and rerun the e2e suite"The receiver reads [from <your alias or tmux name>@<your machine> · reply: <your key>] <message>, so it can answer with the same tool. A name also matches the alias, the name the agent gives its session, or its label. Your own session is left out of name matching, so a project you run on two PCs resolves to the other one. A name that still matches two sessions is refused with both keys listed, and an unknown name is refused with the other sessions listed. A zeph sh shell session is never a target: it is a real shell, and a message typed into it would run as a command on that machine. A session on a machine that is offline is refused (TARGET_OFFLINE): its listener takes commands only while connected, so the message would never be typed. Sending to your own session is refused. The body is plaintext, even with E2E on: the listener drops an encrypted agent.command instead of typing it. Keep secrets out of the message.
Returns: { sent: true, target: "<key>", pushId: "..." }.
Ask the user a question with quick-reply buttons and a text input field — they tap a button or type. Blocks until response or timeout. With no actions it is a plain text prompt (a commit message, a value).
actions is the steering surface: pass 2–4 buttons on nearly every ask (the next-step candidates plus a safe Done-like fallback) and leave it out only when the answer is inherently free-form text — a bare text box on a "done — what next?" ask gives the phone nothing to tap.
Requires ZEPH_HOOK_ID.
title: "What should we do?"
body: "3 tests failed in auth module" (optional)
actions: [{ id: "fix", label: "Fix now", style: "primary" },
{ id: "skip", label: "Skip", style: "secondary" }] (optional, 1-4)
placeholder: "Or type a custom response..." (optional)
inputType: "text" | "multiline" (default: text)
timeout: 120 (seconds, default: 120, max: 600)
fallback: "skip" (auto-select on timeout, optional)Returns: { actionId: "fix", timedOut: false } or { value: "custom text", timedOut: false }
The user can also attach screenshots or files to their answer. Those are downloaded to ~/.zeph/attachments/hook-<eventId>/ and the result gains an attachments array of absolute local paths, alongside the button or the text:
{ value: "look at this", attachments: ["/Users/you/.zeph/attachments/hook-hevt_1/screen.png"],
attachmentsNote: "The user attached 1 file(s) to this answer. Read each path above to see them.",
timedOut: false }Reading those paths is part of reading the answer. Note that hook attachments are never end-to-end encrypted — the same limitation as the question itself, since the hook route carries no sender key.
zeph_ask blocks until the user responds, up to its timeout (max 600s). With wsUrl set in ~/.zeph/config.json the response arrives over WebSocket the instant it's submitted; otherwise the server polls. Either way the MCP request stays open the whole time. To keep the client from giving up early, the server emits a notifications/progress every 5s while waiting. Clients must either set a per-request timeout above the tool's timeout, or reset their timeout on progress notifications. Claude Code does the latter by default.
Lists connected devices with online status. Use to check which devices will receive notifications.
Lists channels the user owns or subscribes to. Use to find channelId for zeph_broadcast.
Situation | Tool | Example |
Long task finished |
| Build complete, test results, deploy done |
Need a decision (buttons + optional free text) |
| "Tests green. Deploy?" with a custom-instruction escape hatch |
Free-form input only |
| Commit message, env var value, description |
Share code/logs |
| Error logs, test reports, generated config |
Share snippet |
| API key, URL, shell command |
Label this session |
| Name the run "Prod deploy" so parallel sessions stay distinguishable on the phone |
Pass work to another agent |
| "Send the summary to the pi session on my other PC" |
Decision gate with an escape hatch (preferred):
zeph_ask(
title: "Tests green. Deploy to production?",
actions: [
{ id: "deploy", label: "Deploy", style: "primary" },
{ id: "hold", label: "Hold", style: "secondary" }
],
placeholder: "Or tell me what to do instead...",
fallback: "hold"
)Task completion notification:
zeph_notify(
title: "Build complete: web app",
body: "All 42 tests passed. Bundle size: 1.2MB (-3%)"
)Error alert with link:
zeph_notify(
title: "CI failed: lint errors",
body: "2 errors in src/auth.ts",
url: "https://github.com/org/repo/actions/runs/456",
priority: "high"
)Short responses the user can see immediately in the terminal
Read-only operations (file search, code analysis)
Every single tool call — only notify on meaningful milestones
When running multiple AI agent sessions in parallel, use zeph_notify to signal completion so the user knows which session finished without checking each terminal.
The API key needs the following scopes:
push:read — for zeph_list
push:write — for zeph_notify, zeph_clipboard, zeph_dismiss, zeph_dismiss_all, zeph_file, zeph_agent_send
hook:write — for zeph_ask
device:write — for zeph_session_rename
channel:read — for zeph://channels resource
Create an API key with the MCP preset in Settings > API Keys for the correct permissions.
End-to-end encryption is off by default and turning it on needs Zeph Pro. The switch is in the app under Settings → E2E Encryption; until you flip it, every push leaves this server in plaintext. If the account later loses Pro the server answers PRO_REQUIRED and this one drops back to plaintext for the rest of the process. No configuration either way — but the opt-in is read once at startup, so turning it on while this server is running takes effect only after a restart.
With it on, push bodies and file attachments are encrypted with AES-256-GCM. Only zeph_notify and zeph_file are encrypted. zeph_ask, zeph_clipboard, zeph_broadcast and zeph_agent_send stay plaintext even then — zeph_agent_send because the target machine's listener drops an encrypted agent.command instead of typing it. This machine holds one ECDH P-256 keypair in ~/.zeph/device-keys.json, shared with zeph listener (which registers its public half on the machine's device record) and created by whichever starts first (the keypair older builds kept in ~/.config/zeph/device-keys.json is deleted) — the private half never leaves the machine, and the backend stores public keys only and rejects a private-key upload. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
Threat model: against a passive backend — a leaked snapshot, an operator reading the table — the stored ciphertext and wrapped keys are useless, so push contents stay private. Three limits worth knowing:
No protection from an active malicious operator. Recipient public keys come from GET /devices on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. The Zeph app ships the counter-measure — compare device fingerprints, mark a device verified, and strict mode then wraps only for verified devices — but it defaults off, its verified list is per browser profile, and this server does not consult it: selectRecipients asks only whether a device has a public key, and whether that key is the legacy account-wide one (ADR-0007 Phase 4).
No forward secrecy. The ECDH secret for a given sender/device pair is static, so compromising either private key opens every past push wrapped for that pair.
senderPublicKey is unsigned, so a swapped one makes a push undecryptable — that direction fails closed rather than leaking.
A device that has not registered a per-device public key cannot be sent to; it is skipped, and if no device qualifies the push goes out in the clear rather than arriving as something nothing can open.
Apache-2.0
Type a message into ANOTHER agent session on any of the user's machines, as if the user sent it from their phone. Use when the user asks you to pass something to another agent. The receiver sees [from <you>@<host> · reply: <your key>] first. Answer such a message with this tool only when it asks for an answer — two agents replying to each other loop.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Session key `<deviceId>:<tmuxName>` as given in a `[zeph: …]` hint or `reply:` header, or a name/alias matching one session | |
| message | Yes | Plain text (not encrypted) typed into the target session |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, destructive-capable operation. The description adds valuable behavioral context: the receiver sees a '[from <you>@<host> · reply: <your key>]' header, and the loop warning cautions against reflexive agent-to-agent replies. This goes beyond the annotations without contradicting them.
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?
Three sentences, each earning its place: the action, the usage trigger, the receiver-visible effect, and the loop caution. It is front-loaded with the core behavior and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with 100% schema coverage and annotations covering safety, the description covers the main operational context: when to use it, what the receiver sees, and a critical anti-loop warning. It does not describe the return/acknowledgment behavior, but no output schema exists and this is a minor gap for a send-style 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?
Schema description coverage is 100%, so the schema already documents both `target` and `message` in detail. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Type a message into ANOTHER agent session' and clarifies the user-facing effect ('as if the user sent it from their phone'). It clearly distinguishes this from sibling tools by emphasizing 'another agent session' and the reply-header behavior.
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?
It gives an explicit when-to-use rule: 'Use when the user asks you to pass something to another agent.' It also provides a when-not-to-use warning about two agents replying to each other in a loop. However, it does not explicitly name alternative sibling tools such as zeph_broadcast or zeph_notify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the user a question on their phone: quick-reply buttons plus a text field — they tap or type. Pass actions (2–4 buttons) unless the answer is free-form text. Blocks until they answer or timeout passes. Requires ZEPH_HOOK_ID. Files the user attaches arrive as local absolute paths in the result's attachments; reading them is part of the answer. Never end-to-end encrypted (unlike zeph_notify / zeph_file), so keep secrets out of the question and do not expect a private answer.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Context or instructions | |
| title | Yes | Question or request title | |
| actions | No | Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a "done — what next?" ask. | |
| timeout | No | Seconds to wait for response (default: 120) | |
| fallback | No | Action ID to auto-select on timeout | |
| inputType | No | Input field type (default: text) | text |
| placeholder | No | Input field placeholder hint |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond these: it reveals that the call blocks until user response or timeout, that attached files arrive as local absolute paths in the result's `attachments`, and that the channel is not end-to-end encrypted. It also notes the requirement for ZEPH_HOOK_ID. These are material behaviors not captured by annotations, and none contradict them.
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 five sentences, each earning its place: purpose, primary usage pattern, blocking behavior, prerequisite, and a security caveat. Critical constraints (actions guidance, secret caution) are front-loaded. There is no fluff or repetition of schema fields, keeping it tightly scoped yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an interactive, blocking tool with encryption limitations and attachment handling, the description covers everything an agent needs: how to frame the question, when to pass actions, timeout behavior, the hook requirement, the attachment result format, and the security posture. The schema documents every parameter, and the description fills in behavioral details like blocking and result shape. No critical omissions 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?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful usage context, especially for `actions`: it explains that actions are quick-reply buttons, that they should carry next-step candidates plus a 'Done-like' fallback, and when it is acceptable to omit them. It also clarifies that attachments are part of the answer, which informs how the result should be interpreted. This is more than a restatement of the schema, hence a 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 opens with a precise, verb-first statement: 'Ask the user a question on their phone: quick-reply buttons plus a text field — they tap or type.' It clearly identifies the resource (the user's phone interaction) and the action (ask). It also distinguishes itself from siblings by explicitly contrasting with zeph_notify/zeph_file over encryption, and through the quick-reply behavior that zeph_notify lacks. The purpose is unambiguous and differentiated.
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?
Explicit when‑to‑use instructions are given: 'Pass `actions` (2–4 buttons) unless the answer is free-form text.' It also states the blocking behavior ('Blocks until they answer or `timeout` passes'), the prerequisite ('Requires ZEPH_HOOK_ID'), and a caution about content secrecy because it is not end-to-end encrypted. The input schema for `actions` reinforces this with guidance on what to include and when to omit, so an agent knows exactly how to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a push notification to all subscribers of a channel. Use zeph://channels resource to find available channels.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional URL to open on the device. | |
| body | No | Notification body text | |
| title | Yes | Notification title | |
| priority | No | Notification priority | normal |
| channelId | Yes | Channel ID to broadcast to (e.g., "ch_...") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description merely restates the sending action without adding behavioral details like rate limits, auth requirements, or side effects (openWorldHint=true suggests unknown side effects). The description lacks additional context beyond what annotations 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 two sentences, front-loaded with the core purpose, and includes a practical usage hint. Every word serves a purpose with no unnecessary 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?
For a tool with five parameters and no output schema, the description explains the primary action and provides a resource lookup hint. However, it fails to describe return values, error conditions, or potential impacts on subscribers, leaving gaps for an AI 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 100%, so the schema fully describes all five parameters. The description does not contribute any parameter-specific meaning, maintaining the baseline score of 3 as per rubric when schema coverage is high.
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 'Send a push notification to all subscribers of a channel' with a specific verb and resource. It distinguishes itself from siblings like zeph_notify by the 'broadcast' nature, but does not explicitly differentiate from zeph_notify, which may cause ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a helpful hint to use zeph://channels to find channels, implying a prerequisite. However, it provides no guidance on when to use this tool versus alternatives (e.g., zeph_notify) or scenarios to avoid, leaving usage context vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy text to the user's device clipboard. The text will appear in their clipboard history and can be pasted immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text to copy to clipboard | |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations, noting that text appears in clipboard history and can be pasted immediately. No contradiction 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?
The description is extremely concise (one sentence, 14 words) and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description adequately covers the action and a key behavioral side effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add significant meaning beyond what the schema already provides.
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 verb 'Copy' and the resource 'text to the user's device clipboard', distinguishing it from siblings like zeph_broadcast or zeph_notify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (clipboard operations) but does not provide explicit guidance on when to use this tool vs alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss (mark as read) a specific push notification by ID. Use after processing a notification to clear it from the user's feed.
| Name | Required | Description | Default |
|---|---|---|---|
| pushId | Yes | Push ID to dismiss (e.g., "push_01HX...") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide behavioral hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds that it clears from the feed, but this is already implied by 'dismiss'. No contradictions; score is adequate but not enhanced.
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?
A single concise sentence that front-loads the action and purpose. No wasted words, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and annotations providing behavioral context, the description is fairly complete. It covers what, when, and how. Minor gap: could mention nondestructive nature, but annotations already cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description and example for pushId. The description adds no further parameter details beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (dismiss), resource (specific push notification), and action (mark as read). It distinguishes from the sibling zeph_dismiss_all by specifying 'by ID' vs. all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use after processing a notification, giving clear context. However, it lacks explicit guidance on when not to use or comparison to other sibling tools, though the distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss all push notifications at once. Clears the entire notification feed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds that it clears the entire notification feed, specifying scope beyond the annotation hints. 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?
Two sentences, front-loaded with action. Every word serves a purpose; no waste.
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?
With zero parameters, annotations present, and no output schema, the description is adequate. It could mention irreversibility or confirmation, but annotations cover destructive behavior.
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?
No parameters exist, so baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it dismisses all push notifications at once, distinguishing it from the sibling zeph_dismiss which likely handles individual notifications. The verb 'dismiss' and resource 'all push notifications' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you want to clear the entire notification feed, and sibling names suggest zeph_dismiss is for individual dismissal. However, no explicit when-not or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a file to the user's device. Pass filePath to send a file that already exists on disk — images (png/jpg/gif/webp/heic), PDFs, logs, anything. Pass content instead to send text you generated. Images render inline on the device.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Notification title (defaults to fileName) | |
| content | No | Text content of the file. Use only for text you generated; requires `fileName`. | |
| fileName | No | File name with extension (e.g., "report.txt"). Required with `content`; defaults to the basename of `filePath`. | |
| filePath | No | Absolute path to a local file to send. Required for images, PDFs, and any other binary — never base64 a file into `content`. | |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the minimal annotations: images render inline, file types are enumerated, and the two modes are explained. It doesn't contain contradictions with the annotations (readOnlyHint=false, destructiveHint=false) and offers useful operational details such as the 'never base64' rule, though it doesn't cover error handling or permission requirements.
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 two sentences, front-loaded with the core action, and packs essential usage guidance without any waste. Every clause contributes meaning, making it an exemplar of concision.
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 covers the main use cases and relies on the schema for parameter details. However, it omits the implicit requirement that at least one of filePath or content must be provided, and doesn't state what happens if neither is passed. Given the optional parameters, this leaves a small completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description significantly enhances parameter understanding by linking filePath to existing files and content to generated text, and clarifying that filePath is required for images/PDFs/binary. The 'never base64 a file into content' warning adds crucial semantics not present in 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 the tool's primary function: 'Send a file to the user's device.' It distinguishes itself from siblings like zeph_notify or zeph_clipboard by focusing on file transfer, and further clarifies two distinct modes (filePath for existing files, content for generated text). This is a specific verb+resource with a clear scope.
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 clear guidance on when to use filePath vs content, including an explicit warning against base64-encoding binary files into content. It lacks an explicit comparison to sibling tools or a 'when not to use' clause, but the context is sufficient for an agent to select it for file-sending tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent push notifications. Use this to check notification history, avoid duplicates, or reference previous messages.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by push type | |
| limit | No | Number of pushes to return (default: 5, max: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds behavioral context like 'list recent' and 'avoid duplicates' (consistent with idempotentHint=true). 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?
Two short, front-loaded sentences with no wasted words. Efficiently conveys purpose and usage scenarios.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, complete annotations (readOnly, idempotent, openWorld), and full schema, the description adequately covers purpose and use cases. No output schema needed per rules. It could mention ordering (recent) is implicit, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters (limit and type). The description adds no additional parameter information beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List recent push notifications' with a specific verb and resource, and adds usage context like checking history, avoiding duplicates, or referencing messages. This distinguishes it from sibling tools like zeph_notify (send) and zeph_dismiss (dismiss).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to check notification history, avoid duplicates, or reference previous messages,' providing clear scenarios. It lacks explicit when-not-to-use or naming alternatives, but the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a one-way push notification to the user's devices. Use this to inform the user about task completion, errors, or status updates. Long bodies are automatically uploaded as a file for full viewing.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional URL to open on the device. | |
| body | No | Notification body text | |
| title | Yes | Notification title | |
| priority | No | Notification priority. Use "urgent" for critical alerts, "low" for background info. | normal |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and open world effects (openWorldHint=true). The description adds that long bodies are automatically uploaded as a file, which is a useful behavioral trait beyond annotations. 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?
Two concise sentences: first sentence states core purpose, second adds usage examples and a key behavioral note. No redundant words, front-loaded with important 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?
For a simple notification tool (5 params, no output schema), the description covers purpose, usage, and the file upload behavior. It lacks details on return value or error cases, but is adequate for most agents given the low 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 coverage is 100%, but the description adds rich context: explains priority enum usage ('urgent' for critical, 'low' for background), describes targetDeviceId behavior (omit for default/all), and notes file upload for long bodies. Adds significant value 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 it sends a one-way push notification to user devices, with specific use cases like task completion, errors, or status updates. This distinguishes it from siblings like zeph_ask (two-way) and zeph_broadcast (different broadcast mechanism).
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 gives explicit usage context (inform about task completion, errors, status updates) but does not explicitly mention when not to use or compare with alternatives like zeph_ask or zeph_broadcast. Still provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a custom display name for THIS agent session in the user's Zeph app (the Streams › Agents list). Label what this session is working on — e.g. "Prod deploy" or "Auth refactor" — so the user can tell parallel sessions apart on their phone. Renames the current session; the name persists until changed.
| Name | Required | Description | Default |
|---|---|---|---|
| alias | Yes | Display name for this session (max 60 characters). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, open-world, non-destructive operation. The description adds context that the rename persists until changed and targets 'THIS agent session' specifically, making the side effects clear. This goes beyond simply restating the 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 three sentences with no fluff. The first sentence states the action, the second provides usage guidance with examples, and the third clarifies persistence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, no output schema, and helpful annotations, the description fully covers the action, the context of use, and the durability of the change. There are no missing details that would cause an agent to misuse 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?
The schema already covers the single parameter 'alias' with a description. The tool description enhances this by giving examples of valid labels and explaining the purpose behind the parameter ('Label what this session is working on'), adding meaning 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 immediately states the tool's function with a specific verb and resource: 'Set a custom display name for THIS agent session.' It clearly differentiates from sibling tools by specifying this is for renaming the current session in the user's Zeph app, not any other action like notifications or prompts.
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 a concrete use case: labeling sessions so the user can distinguish parallel sessions on their phone, with examples ('Prod deploy', 'Auth refactor'). It doesn't explicitly state when not to use it, but since this is a unique action among siblings, the context is clear enough.
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.
v3.2.0zeph_agent_sendv3.0.0zeph_inputzeph_promptv2.3.0zeph_ask1 field changedInput schema / properties / actions / descriptionPrevious value: -"Quick-reply buttons (1-4). Omit for text-only input"New value: +"Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a \"done — what next?\" ask."v2.2.0zeph_file4 fields changedInput schema / properties / content / descriptionPrevious value: -"Text content of the file"New value: +"Text content of the file. Use only for text you generated; requires `fileName`."Input schema / properties / fileName / descriptionPrevious value: -"File name with extension (e.g., \"report.txt\", \"output.json\")"New value: +"File name with extension (e.g., \"report.txt\"). Required with `content`; defaults to the basename of `filePath`."Input schema / properties / filePathAdded value: +{
+ "description": "Absolute path to a local file to send. Required for images, PDFs, and any other binary — never base64 a file into `content`.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "fileName",
- "content"
-]zeph_session_renamev1.11.2zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.11.0zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.10.0zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.9.2zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.4.0zeph_askScored across 10 tools
Most tools map to distinct communication/notification actions, and descriptions clarify the recipient and medium. zeph_notify, zeph_broadcast, zeph_file, and zeph_clipboard all deliver content to devices and could be confused at a glance, though their purposes are ultimately different.
All tools share the zeph_ prefix, but the naming convention varies: some are bare verbs (zeph_notify, zeph_ask), some are nouns used as actions (zeph_file, zeph_clipboard), and some are object_verb (zeph_agent_send, zeph_session_rename). This is readable but not a predictable pattern.
Ten tools is well-scoped for a device notification and messaging server. The set covers sending, listing, dismissing, asking, file transfer, clipboard, agent messaging, and session naming without feeling bloated or redundant.
The core notification lifecycle (send/list/dismiss/dismiss_all) and key communication paths (ask, file, agent send) are present. Channel management is delegated to a resource and there is no explicit notification update, but these are minor gaps rather than blockers.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
An MCP memory server. One memory your agents share — across models, devices and apps.
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
MCP server for building and testing AI agents with multi-model experimentation and insights.
