MCP Write Tools vs Read: 8 Fused, 1 Pure

MCP itself does not have a separate primitive for the two. Both are Tools. What it has are annotations: readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. A read tool is a Tool whose readOnlyHint is true and that does not mutate any external state. A write tool is the inverse. Annotations are hints, not enforcement. The MCP spec says the same thing: clients use them for UX (do I prompt before invoking?), not for sandboxing. So the read-vs-write distinction lives entirely in the server's design choices.

Because the surface is a live UI. After clicking a button, the only useful next thing for the LLM to know is what changed in the accessibility tree. Splitting click and refresh into two tools means every click is followed by a refresh, every time, with no exceptions. That is two round trips for one logical operation, and it introduces a class of bugs where the LLM forgets to refresh and reasons against stale tree state. Fusing them into click_and_traverse eliminates the second round trip and makes the post-action state structurally part of the tool's return value. The server returns a diff (added, removed, modified, attribute changes) so the LLM sees exactly what the click moved, not just the new state.

Nine tools total. Eight are fused write+read: open_application_and_traverse, click_and_traverse, type_and_traverse, press_key_and_traverse, scroll_and_traverse, set_value_and_traverse, press_ax_and_traverse, set_selected_and_traverse. One is pure read: refresh_traversal. The aggregate list lives at Sources/MCPServer/main.swift line 1482, and the dispatch case block runs from line 777 to line 853. Every one of the eight fused tools ends in _and_traverse in its tool name string, on purpose. The naming is the contract.

When the read is expensive and the LLM does not need it after every write. A database MCP server is the canonical case: SELECT is cheap and the LLM rarely needs the entire table after an INSERT. The filesystem reference server splits read_file from write_file for the same reason. A vector-search MCP server splits search_documents from index_document because indexing is async and search is independent. Fuse when the write changes a stateful surface the LLM has to keep modeling: a UI tree, a board game, a simulator, a chat thread, a live document. The test is: after the write, does the LLM still need the surface? If yes, fuse.

Four arrays: added, removed, modified, and attribute changes. After click_and_traverse, the macOS-use server walks the accessibility tree, compares it to the pre-action snapshot, and returns the structural diff plus a small text-changes block (up to three modified text or AXValue fields, truncated to 60 characters per side). The diff is what tells the LLM whether the click did anything. If the diff is empty, the click was dropped. If the diff shows a new modal window appeared, the LLM knows to interact with the modal next. The summary line code lives at main.swift lines 858 to 878.

Yes. A fused tool cannot honestly set readOnlyHint to true because it mutates state, and it cannot reasonably set readOnlyHint to false alone because the bulk of its return value is observation. The macOS-use server simply does not lie in the annotation: every fused tool is implicitly a write tool from the spec's perspective. The pure read (refresh_traversal) is the one tool that could carry readOnlyHint true. This is a real downside of fusion: clients that auto-allow read-only tools but prompt for writes will prompt on every fused call. For UI driving that is correct behavior. For other surfaces it would be too noisy.

You can, and several MCP servers do. The pattern is: write tool returns a snapshot ID, then a separate read_diff tool takes a before-snapshot-ID and an after-snapshot-ID and returns the diff. It works, and it preserves clean readOnlyHint annotations. The cost is one extra round trip and a stateful snapshot store on the server. The macOS-use server skipped that path because the diff is small (typical AX traversals are 100 to 800 elements, and a click usually mutates 1 to 20 of them) and shipping it inline costs nothing. The choice is taste and surface, not correctness.

Some. Browser-use MCP servers tend to fuse navigate_and_screenshot or click_and_screenshot for the same reason: the LLM driving a page needs the new page after every action. The Playwright MCP server has a click action whose return includes a snapshot reference. Database servers usually do not fuse: queries and mutations are kept distinct. Filesystem servers do not fuse: read_file and write_file are separate, and that is the right call because writing a file does not implicitly change what the LLM should read next. Fusion is correct for live-state surfaces, splitting is correct for transactional surfaces.

In main.swift around line 787, the case for click_and_traverse picks the click handler, runs it, then runs the traversal in the same call frame, then builds a summary that includes a buildDiffSummary call (line 791). The summary line ends with the diff. There is no second tool dispatch, no second JSON-RPC round trip, and no second permission prompt. The traversal cost is amortized across the click cost because both go through the same AXUIElement timeout and the same response serializer.

Use refresh_traversal. It is the dedicated pure read at main.swift line 1383 and its description literally says "Useful for getting the current UI state without performing an action." It takes a PID and returns the same structured tree the fused tools return. The reason to keep it separate is exactly this case: the LLM sometimes needs a fresh tree without doing anything (the user reopened the app, time passed, an external event likely changed the UI). Splitting refresh from the eight write tools is the right call. Splitting click from refresh would not be.

It costs slightly less than a separate read. Same AXUIElementCreateApplication call, same tree walk, same serialization. The savings come from skipping the JSON-RPC encode/decode cycle, the MCP transport hop, the permission check on the client (if it prompts on every tool call), and the LLM context budget for an extra tool call message. On macOS 14 the entire fused click_and_traverse on a 400-element app finishes in 220 to 380ms end to end, of which roughly 180 to 320ms is the traversal. A separate refresh would add another 200ms on average. Three writes plus three reads in sequence are 1.2 seconds; three fused are 700ms.

It can if the diff is presented poorly. The macOS-use server addresses this by writing the diff into a structured summary at the top of the response (see main.swift lines 856 to 878) and writing the full traversal to a side file the LLM only reads if it needs to. So the LLM gets a one-line summary like "Clicked at (132, 280). 1 added, 0 removed, 2 modified." plus a file path it can grep. The LLM never has to wade through an 800-element tree to find what changed. The fused contract becomes legible at the model's context budget rather than overwhelming it.