DEV Community

Elena Dev
Elena Dev

Posted on

Our booking API worked. Assistants still could not find the door

In August I put a public booking API online, and then an MCP server on top of it. No key, no account. Any assistant could read live availability at a restaurant and create a real booking with a confirmation ID. In our own tests it worked on the first try.

A few days later a real conversation landed on my desk. A guest had asked ChatGPT for a table at a restaurant that runs on our system. It found the restaurant. It read the restaurant's own website. Then it said it could not search the reservation inventory, and offered the guest another place with a confirmed table instead.

Nothing we had shipped was broken. Everything the assistant needed existed. It was all in places a browsing model never looks.

A description is not a door

This was the same gap we keep measuring from the outside. Restaurants have noticed a new kind of reader. More of them now publish an llms.txt, a plain text file that explains a business to a language model. Almost none of them give that reader a way to book.

I had managed the mirror image. I had built the way to book and forgotten to tell anyone where it was.

Where the instructions were hiding

Our venue pages are a React app. The booking instructions lived in two places: the server component payload and a set of meta tags. Both are perfectly readable if you know to look. A browsing assistant does not look there. It reads the visible text, roughly the way a person skims a page, and decides from that.

It was worse than that. The llms.txt on the product domain was serving the studio's file, which is about websites and branding and says nothing about booking a table. The one file written for language models was describing the wrong product.

Four ways in, one booking

The fix was not one change. Different assistants have different hands, so a booking now has four entrances, and every one of them ends in the same reservation.

A plain GET for availability. Any assistant that can fetch a URL can read real slots, with no tools at all:

GET https://g-guest.app/api/cal/v1/{slug}/availability?date=YYYY-MM-DD&party=2
Enter fullscreen mode Exit fullscreen mode

A REST call to book. POST the chosen start plus the guest's name, phone and email to /api/cal/v1/{slug}/bookings. There is no key, on purpose. An assistant acting for a stranger has no key and cannot get one. The guest's own details are the identity that matters.

An MCP server, for clients that call tools. It launched in August with four tools. It has eight now: search, fetch, get_business, check_availability, create_booking, check_booking, cancel_booking and request_listing. Most of the additions cover what happens after a booking exists, because people check bookings and cancel them. The last one lets a business that is not on the system yet ask to be.

A booking page with no JavaScript. The regular booking page renders the date picker, the slots and the submit button in the browser. An assistant reading the raw HTML sees an empty container. We tested it with a real assistant, which reported that it could tell booking happened on this page but had no action available. So every venue now has a twin at /book/{slug}/simple: slots rendered on the server, a plain <form method="post">, nothing to execute. It doubles as the accessible path for people. It is canonical to the main page, so search engines do not split the two.

Putting the sign where the reader reads

Building entrances was half the job. The other half was putting directions where each kind of reader actually looks.

Visible text at the bottom of every venue page. The availability URL, the MCP endpoint, and one sentence for an assistant that cannot act at all: do not tell the person this venue cannot be booked, because it can. That last line matters most. The failure in that conversation was not that the assistant could not book. It was that it told the guest no.

An llms.txt on the product domain, written as instructions instead of marketing. Its first section is headed, literally, "If you are an AI assistant, read this part."

A manifest at a predictable path. There is no standard for a booking manifest yet, so /.well-known/g-guest.json is our own convention. It is unauthenticated and cheap to parse. Trimmed:

{
  "service": "G-Guest",
  "auth": { "required": false },
  "mcp": {
    "endpoint": "https://g-guest.app/api/mcp",
    "transport": "streamable-http (JSON-RPC 2.0 over POST)"
  },
  "html_booking": { "url": "https://g-guest.app/book/{slug}/simple" },
  "try_it": { "slug": "demo" }
}
Enter fullscreen mode Exit fullscreen mode

/.well-known/mcp.json, which is where an MCP client looks on its own, now answers too.

The comment at the top of the manifest's source file says it better than I can: the sign was lit, the door had no handle on the outside. This file is the handle.

Make the outcome a field

One more thing I would do from day one. A booking response is not always "confirmed". Some venues want the guest to confirm by link. Some take a prepayment. So the response carries a status, confirmed, pending_confirmation or pending_payment, plus an expires_at. The manifest tells the assistant in plain words: if it is pending, show the guest the link, and do not say it is booked before then.

An assistant that tells a guest "you're booked" while the table is about to be released does more damage than one that says nothing. The status has to be a field, and the instruction about what not to claim has to sit next to it.

What I would tell anyone building for agents

  • A description is not a door. An llms.txt that explains you is good. It is not a way in.
  • Put the door where the reader reads. Not in meta tags, not in a hydration payload. Visible text, a predictable path, a file written for models.
  • Give every kind of client its own entrance: a GET for browsing assistants, a POST for API callers, tools for MCP clients, a form for anything that can submit HTML.
  • Make the outcome a field, and say what must not be claimed before it is final.

You can try all four on the demo venue. The manifest is at https://g-guest.app/.well-known/g-guest.json. Or point your assistant at https://g-guest.app/book/demo, ask it for a table for two on Friday at seven, and tell me where it stops.

A question for anyone who builds agents: when yours lands on a site it has never seen, how does it find out what that site can do? Does it read llms.txt, look for a well-known path, or just parse the page? I would like to know which sign actually gets read.

Elena OS

Top comments (0)