Hookdeck has released Inspect, a webhook tester designed specifically for AI agents, after discovering that most existing tools fail when stripped of Model Context Protocol (MCP) integrations. The team’s research, detailed in a November 2026 blog post, reveals that agents struggle with client-rendered single-page applications and complex headers, preferring simple, server-rendered HTML with explicit instructions. This shift in design philosophy prioritizes compatibility across diverse agent harnesses over modern API standards.

The Failure of Modern Web Standards for Agents

The Hookdeck team initially assumed that standard web practices would translate directly to agent usage. They found that fetch tools used by agents are often blunt instruments that cannot set request headers, summarize content aggressively, or handle caching correctly. One notable failure involved an agent calling a wait endpoint, receiving a timeout, and then calling the same URL 41 times because its fetch tool served the cached timeout response, causing the agent to believe it had waited 17 minutes when the event had arrived seconds prior. To counter this, the team enforced Cache-Control: no-store and ensured every resume URL was unique.

Why Plain Text Instructions Beat JSON and llms.txt

Attempts to use machine-readable discovery files like llms.txt or embedded JSON blocks for actions resulted in near-zero uptake. The study showed that agents do not look for site-level discovery files; they only read the specific URL they are given. When the team placed plain text instructions directly on the server-rendered page, agents found the wait endpoint 100% of the time. Conversely, when instructions were hidden in client-side JavaScript or separate files, success rates dropped to 0%. The first line of the page now explicitly states the status and the next step, ensuring that even aggressive summarizers retain the critical action item.

Environment Constraints Dictate API Design

A major insight from the project was that failures often stemmed from the agent's execution environment rather than the model's reasoning. Features like streaming (text/event-stream) and background watchers frequently failed because harnesses blocked background processes or ended sessions before events arrived. The solution was to design for the least capable client: one foreground request, no background work, and no reliance on headers. By using query parameters instead of headers and ensuring endpoints return immediately with parsed payloads, Hookdeck Inspect bypasses many of the sandbox limitations that plague modern agent frameworks.

Key Takeaways

  • Server-rendered HTML with visible text instructions is superior to client-side apps or machine-readable discovery files for agent compatibility.
  • Caching is a critical failure point for agents; unique URLs and no-store headers are essential for accurate state retrieval.
  • Background processes and streaming often fail in agent harnesses; blocking GET requests with immediate responses are more reliable.
  • Different models react differently to instructions; explicit descriptions of endpoint behavior work better than command-like directives to avoid prompt injection alarms.

The Bottom Line

Stop over-engineering your APIs for agents. The most effective interface isn't a complex protocol like MCP, but a boring, server-rendered HTML page that speaks plain English and respects HTTP caching rules. If your agent can't read it in one fetch, it doesn't exist.