Merge

Merge Agent Handler Documentation Audit

The docs read well in isolation but fall apart at the seams: a top-level llms.txt that hands agents the wrong auth headers for this product, a 404'd connector index, a "Companies API" link that points at the registered-users endpoint, an architecture page promised but missing, and a tool-naming convention surfaced only in the logs page.

1. llms.txt documents the wrong authentication headers for Agent Handler (critical)

Location: https://docs.merge.dev/llms.txt vs. /merge-agent-handler/agent-handler and /merge-agent-handler/administer/access-keys

Problem: The top-level llms.txt — the file specifically designed for AI agents to ingest — states: "Authentication requires two headers: Authorization: Bearer <API_KEY> and X-Account-Token: <ACCOUNT_TOKEN>." That describes the Unified API. Agent Handler, which is one of the three products listed on the same page, only requires Authorization: Bearer <YOUR_API_KEY> (per the access-keys page and the management-plane reference). There is no X-Account-Token in any Agent Handler request.

Consequence: An LLM ingesting llms.txt to learn how to call Merge's products will hallucinate an X-Account-Token header on every Agent Handler call. The most likely failure mode is silent: the header gets ignored, but if a downstream proxy validates header presence, the request 400s with no signal that the doc is the source of the error. This is the single most agent-hostile defect in the docs.

The fix: Split the authentication section in llms.txt by product. State explicitly: Unified API uses Authorization + X-Account-Token; Agent Handler uses Authorization only; Gateway has its own scheme. Mirror this split in llms-full.txt.

2. The Connectors index 404s, and the troubleshooting page links to it with the wrong casing (critical)

Location: /merge-agent-handler/connectors (404) and /merge-agent-handler/resources/troubleshooting

Problem: The bare connector index page /merge-agent-handler/connectors returns "This page does not exist." Worse, the troubleshooting page tells developers to "Confirm the Connector slug against the Connector catalog" — note the capital C. On a case-sensitive route, that link will not resolve even if a lowercase index existed. Individual subpages like /connectors/stripe and /connectors/slack do work, but there is no working hub linking them.

Consequence: A developer hitting the most common Magic Link failure ("the Connector slug doesn't exist") follows the troubleshooting link to verify a slug and lands on a 404. They have no canonical list of which connectors exist, which slugs to use, or how slugs are formatted beyond the two examples (google-drive, microsoft-teams) given inline.

The fix: Publish a real /merge-agent-handler/connectors index page listing every connector with its slug, and rewrite the troubleshooting link to the lowercase canonical path. Add a redirect from /Connectors to /connectors to catch the typo.

3. "Companies API" link points at the registered-users endpoint, and no Companies endpoints actually exist (critical)

Location: /merge-agent-handler/build/users/companies-and-groups

Problem: The companies-and-groups page tells developers: "For Company management endpoints (renaming, deletion, listing users in a Company), see the Companies API reference." The link text says "Companies API" but the URL points to the Registered Users reference. The same page also states: "There's no separate 'create Company' endpoint. The first Registered User with a new origin_company_id creates the Company implicitly." So the doc promises rename, deletion, and listing endpoints, then links to a different resource, and elsewhere says no dedicated Company endpoints exist.

Consequence: A developer trying to rename or delete a Company has no idea whether (a) the endpoints exist and the link is wrong, (b) the endpoints live inside the Registered Users API, or (c) Company management is just unsupported. For an agent (LLM) trying to plan a multi-tenant workflow, this contradiction is unrecoverable — there is no programmatic way to disambiguate.

The fix: Either ship a real Companies API reference and link it correctly, or remove the promise and explicitly document that Companies are implicit-only with no management endpoints. Pick one and align the prose.

4. The architecture page is referenced but does not exist (significant)

Location: /merge-agent-handler/architecture

Problem: The overview funnels readers toward "understanding the architecture," and the URL /merge-agent-handler/architecture returns "This page does not exist." A second URL surfaced in search, /merge-agent-handler/implementation-guides/mcp-integration, also 404s — the working canonical is /merge-agent-handler/build/connecting-agents/mcp-integration.

Consequence: Two of the most natural URLs a developer or agent would guess return 404. The product positions itself as enterprise-grade ("OAuth-authenticated MCP server, SSO and SCIM, custom roles, audit-trail export") but offers no architecture diagram or systems-level overview to back that up. Security-conscious buyers can't trace the request path before adopting.

The fix: Either build the architecture page (request flow, where credentials live, what crosses the trust boundary, how SCIM/IdP plug in) or remove the references and add a redirect from /architecture to a real overview. Redirect the /implementation-guides/mcp-integration ghost path to the canonical /build/connecting-agents/mcp-integration.

5. MCP endpoint URL has an undocumented trailing-slash sensitivity and inconsistent path-parameter naming (significant)

Location: /merge-agent-handler/agent-handler/mcp/endpoint-post vs. /merge-agent-handler/build/connecting-agents/integrating-with-copilot-studio

Problem: The MCP endpoint reference documents the URL as https://ah-api.merge.dev/api/v1/tool-packs/{tool_pack_id}/registered-users/{registered_user_id}/mcp/ — with a trailing slash and snake_case parameters. The Copilot Studio integration guide documents the same endpoint as https://ah-api.merge.dev/api/v1/tool-packs/{Tool Pack ID}/registered-users/{Registered User ID}/mcp — no trailing slash, and with spaces inside parameter names. Neither page acknowledges the other variant.

Consequence: A developer copying the URL from one page and a code snippet from another may get a redirect or 404 depending on the trailing slash. More importantly, the parameter-name mismatch ({Tool Pack ID} with spaces vs. {tool_pack_id} snake_case) breaks copy-paste templating in any tool that substitutes by name — including most agent IDEs that handle these patterns programmatically.

The fix: Pick one canonical URL form (with or without trailing slash) and use it everywhere. Standardize path-parameter naming on the snake_case form across every page, including vendor integration guides.

6. Bearer prefix requirement is only documented on the Copilot Studio page (significant)

Location: /merge-agent-handler/build/connecting-agents/integrating-with-copilot-studio vs. /merge-agent-handler/administer/access-keys and /merge-agent-handler/agent-handler

Problem: The Copilot Studio guide spells out a critical gotcha: "your API key must include the Bearer prefix (with trailing space). Without it, requests to Agent Handler will fail with 401 Unauthorized." The access-keys page says keys are "transmitted in the Authorization header as Bearer <YOUR_API_KEY>" and the API reference says "Bearer token format" — but neither calls out that some MCP clients require the developer to type the literal string Bearer (with space) into a key field, vs. clients that prepend it automatically.

Consequence: Developers integrating through any non-Copilot-Studio client hit a 401 with no obvious cause. The exact symptom ("If your tool list appears empty…") is documented for Copilot Studio only. An agent troubleshooting on behalf of a developer will not find the relevant guidance without specifically searching the Copilot Studio page.

The fix: Move the Bearer prefix gotcha into a top-level authentication page or troubleshooting symptom ("tool list empty / 401 on MCP") rather than burying it in one vendor integration guide.

7. Connector pages list capabilities but include zero code samples or required scopes (significant)

Location: /merge-agent-handler/connectors/stripe, /merge-agent-handler/connectors/slack

Problem: The Stripe page lists tools like "Retrieve the current balance of your Stripe account…" with the explicit note: "The page contains no code samples—only tool descriptions and capabilities." The Slack page enumerates 40+ tools across channels, messages, reactions, users, search — also with no code samples, no list of required OAuth scopes, and no mention of which tools require Bot vs. User tokens. Authentication is summarized as "OAuth authentication" with nothing about scopes.

Consequence: A developer choosing whether to register custom Application Credentials (which the docs recommend for production: "Scope control — You can request only necessary OAuth permissions") has no way to know which scopes the Merge connector actually uses. An agent trying to call pin_message cannot determine whether the configured OAuth grant covers pins:write until it fails at runtime.

The fix: Add a required-scopes table per connector and at least one runnable tools/call example showing the exact JSON arguments. Slack, in particular, needs scope-by-tool mapping because of its split between bot, user, and admin tokens.

8. Tool-naming convention <Connector>__<tool> is documented only in Tool Call Logs (significant)

Location: /merge-agent-handler/observe/tool-call-logs vs. /merge-agent-handler/agent-handler/mcp/endpoint-post and /merge-agent-handler/build/cli/merge-cli

Problem: The Tool Call Logs page introduces the convention in passing: tool name is "formatted as <Connector>__<tool>" (note the double underscore). This naming format is the only way to identify or call a specific tool — but the MCP endpoint reference, the CLI reference, and the connector pages never spell out the convention. The CLI's merge execute-tool <tool> command and the MCP tools/call method both depend on this format, yet neither documents it where developers actually look first.

Consequence: A developer calling tools/call with params.name: "send_message" or merge execute-tool send_message gets an error because the real name is slack__send_message. The convention is discoverable only by tracing through the observability page that most developers will not read until something has already broken. Agents inferring tool names from connector page lists ("Send a message to a Slack channel") will hallucinate names that don't exist.

The fix: Document the <Connector>__<tool> format on the MCP endpoint reference, the CLI page, and at the top of every connector page. Include the literal full name next to each tool description on connector pages.

9. Quickstart Option B is missing or unfinished (significant)

Location: /merge-agent-handler/quickstart

Problem: The Quickstart page presents the setup as a binary choice — "two paths: Merge CLI or raw MCP" — and renders "Option A: Merge CLI" with a description, install/setup instructions, and a horizontal-rule separator. Option B (raw MCP) is never rendered on the page in the scraped content. The page's own framing ("Pick one path") promises two; only one appears.

Consequence: Developers who don't want to install pipx, or are on a non-Python stack, are left without the alternative path the page promised. Agents parsing the quickstart will conclude there is only one option, and won't surface the raw-MCP setup as a viable choice. The page reads as truncated mid-document.

The fix: Restore the Option B section with the raw MCP URL, the credentials it requires, and a worked example. If Option B was intentionally removed, rewrite the lead-in to reflect a single recommended path.

10. Magic Link token endpoint documentation is partial and lacks error responses (significant)

Location: /merge-agent-handler/build/authentication/magic-link and /merge-agent-handler/build/authentication/link

Problem: Both pages reference minting a Magic Link via a backend POST to /link-token but do not show the full URL form (e.g. https://ah-api.merge.dev/api/v1/link-token) inline, and neither page demonstrates the error payloads developers will see when an expired or reused token is presented. The troubleshooting page lists "the link token has expired" and "the link token is being reused after a successful authentication" as the dominant Link failures — but the canonical Link docs don't show the error response shape.

Consequence: Developers debugging an expired-or-reused token failure can identify the cause from troubleshooting but cannot match the exact JSON error structure they're seeing. Agents that need to handle these errors programmatically have no schema to parse against.

The fix: Show the full method + URL + canonical error response payload for the two dominant Link failure modes on the Magic Link page, and link to the reference page from both Link and Magic Link guides.

11. SDKs are "in development" while the API reference shows 8 language examples that aren't SDKs (minor)

Location: /merge-agent-handler/agent-handler and /merge-agent-handler/agent-handler/mcp/endpoint-post

Problem: The management-plane API reference notes that "Official SDKs are in development," requiring direct HTTP client usage. The MCP endpoint reference shows "complete working examples in 8 languages: Python, JavaScript, Go, Ruby, Java, PHP, C#, Swift" — but these demonstrate JSON-RPC calls, which are raw HTTP, not SDK code. Nothing in either page labels the snippets as raw-HTTP nor explains the SDK roadmap.

Consequence: Developers and agents reading the API reference can't tell whether the 8-language examples are forthcoming SDK previews or just hand-rolled HTTP calls, and there is no timeline for the promised SDKs.

The fix: Label the 8-language examples as raw-HTTP JSON-RPC snippets explicitly. Publish an SDK roadmap (which languages, what status) on the API reference landing page.

12. Rate-limit and pagination defaults appear once in the API reference and aren't cross-linked from troubleshooting (minor)

Location: /merge-agent-handler/agent-handler and /merge-agent-handler/resources/troubleshooting

Problem: The management-plane reference states "600 requests per minute for read operations and 120 requests per minute for write operations by default" and "cursor-based pagination with a default limit of 50 items (maximum 250)." The troubleshooting page documents third-party rate-limit symptoms (rate_limit_exceeded) but never mentions Agent Handler's own 429 surface or what limits the 50/250 pagination implies.

Consequence: Developers building list-and-paginate flows or rate-sensitive integrations will discover Agent Handler's own limits through 429s rather than upfront. The troubleshooting page is the natural place to look when seeing a 429, and it doesn't acknowledge that some 429s come from Agent Handler itself, not the third party.

The fix: Add a "Limits" symptom block to the troubleshooting page covering Agent Handler's own 429 behavior, cross-linking the rate-limit numbers in the API reference.

13. Copilot Studio 70-tool cap is documented as a symptom but not in the Tool Packs guide (minor)

Location: /merge-agent-handler/build/tools/tool-packs vs. /merge-agent-handler/resources/troubleshooting

Problem: Troubleshooting lists: "Copilot Studio caps at 70 tools. Tool Packs with more than 70 tools fail to load past the limit." The Tool Packs guide itself, which is where developers decide how many tools to bundle, doesn't mention this cap or any platform-specific tool-count limits.

Consequence: Developers design a Tool Pack with 120 tools for a Copilot Studio agent, ship it, and discover the cap only when tools silently disappear. The forward-looking guide should warn them; the reactive troubleshooting page shouldn't be the first mention.

The fix: Add a "Platform tool-count limits" table to the Tool Packs guide listing each MCP client's known caps, and cross-link the Copilot Studio integration page.

14. CLI documents two auth modes without explaining when to use each (minor)

Location: /merge-agent-handler/build/cli/merge-cli and /merge-agent-handler/use-cases

Problem: The CLI reference documents both "API-key mode" (merge configure) and "OAuth-mode" (merge login / merge logout) as commands in the same table, without explaining when each applies. The use-cases page maps OAuth-via-merge login to "Local development" only, but a developer landing on the CLI reference directly cannot tell that API-key mode is intended for production agent code and OAuth is intended for human local use.

Consequence: A developer setting up CI may use OAuth mode (which requires browser interaction and won't work headlessly), or a local developer may put an API key on a shared machine when OAuth would have been more appropriate. The CLI reference is the canonical entry point and doesn't disambiguate.

The fix: Add a one-paragraph "When to use which auth mode" block at the top of the CLI reference, cross-linking the use-cases page.

What they do well

• The troubleshooting page is unusually concrete — it pairs each symptom with a specific cause and error_type string, which is exactly what agents need to recover.
• The CLI reference clearly documents credential resolution order (flags > env vars > config file) and warns about the plaintext config file with a chmod 600 recommendation.
• The Security Gateway page is honest about its limits: "not a substitute for end-user consent and contracts when handling regulated data" — a refreshing line.

Top 3 recommendations

1. Fix llms.txt to split auth by product. This is the single most consequential change for AI-agent ingestion — every agent reading the file today will mint Agent Handler calls with a header that doesn't belong.
2. Ship the missing index and architecture pages and fix the case-sensitive /Connectors link. Build /connectors, build /architecture, and resolve the casing typo — these three changes close the largest "dead reference" cluster.
3. Make every connector page agent-runnable, and document the <Connector>__<tool> naming convention where developers call tools. Add required OAuth scopes, one runnable tools/call example per connector, and the double-underscore naming pattern on the MCP and CLI references.