Back to engineering

Engineering

MCP structured output and tool annotations in a real booking server

The Bookatu engineering team7 min read

Our business MCP server lets a connected AI app read and change a business's bookings and catalog. We moved it onto the newer protocol features. Here is what tool annotations and output schemas changed in practice, and how clients written for the old protocol kept working unchanged.

The short version

  • Every tool has a title and states every hint, true or false: readOnlyHint, destructiveHint and openWorldHint. None is left to the protocol's default.
  • Every read tool declares an outputSchema and returns structuredContent beside the JSON text it always returned. Writes declare none.
  • A schema says only what is true of every answer, and leaves extra properties open, so adding a field later breaks no client.
  • A tool's own refusal, such as a time that was just taken, comes back as an isError result with a code. Auth, scope and rate-limit refusals stay protocol errors.
  • A client that sends no protocol version header keeps the text answers and the errors it always had.

The business MCP server is how a connected AI app works with a Bookatu business. It can make a booking or add a product, within the scopes the business gave it. For a long time it spoke the 2024-11-05 version of the protocol, and every answer was one block of JSON text.

The server now negotiates 2025-06-18, 2025-03-26 or 2024-11-05. A client that asks for one of those gets it. A client that asks for anything else gets the newest of the three. A few additions from those versions changed how clients use our tools.

Annotations: say every hint out loud

Annotations are hints a client uses to decide how careful to be. readOnlyHint says a tool changes nothing. destructiveHint says a write may change or remove something already there. openWorldHint says the tool reaches beyond the server's own data.

The defaults are the part people miss. For a tool with no annotations, the protocol assumes the worst: not read-only, destructive and open-world. That is a sensible default for a tool nobody knows. It is a poor description of one you wrote. Unannotated, adding a yoga mat to a catalog looks as risky as cancelling a client's lesson, and a client that asks before every risky call asks before every call.

So every tool sends every hint, read straight off its registry entry:

ts
function annotationsFor(spec: ToolSpec) {
  return {
    title: spec.title,
    readOnlyHint: spec.access === "read",
    destructiveHint: spec.destructive === true,
    openWorldHint: spec.openWorld === true,
  };
}

Destructive marks a write that changes or removes what is already there: cancel, decline, reschedule, update, unpublish, mark attendance. Making something new is not destructive. Open-world marks any tool that emails or texts a client, calls an outside URL, or publishes to the public web.

Our first list of open-world tools was written by hand, and review found it missed some. Cancelling a visit emails the client. Publishing a blog post puts it on the public web. Neither was marked, and a client that trusted the hint would have let them run without asking. The hints now come from fields on each tool's entry, and a test reads the tools as tools/list serves them and checks each one against the rule. A tool whose description says the client is emailed must say openWorldHint: true.

Hints are not enforcement. A client may ignore them, and the server still checks the scope and the permission on every call. They exist so a careful client can ask the person at the right moments, and not at every moment.

Output schemas: promise only what is always true

Since 2025-06-18 a tool can declare an outputSchema and return its answer as structuredContent that fits it. The appeal is clear: a client gets typed data instead of parsing text.

The catch is in how clients use it. A client validates structuredContent against the schema, and if it does not fit, the client discards the answer. A schema that is a little too strict does not fail gently. It turns a working tool into a broken one, for one business, on the day one field happens to be empty.

So our schemas follow a few rules:

  • List the top-level keys, and mark as required only those present in every answer.
  • Inside a list, describe only the fields of each row that are certain, and allow null wherever the stored value can be empty. A service may have no description. A booking may have nobody assigned yet.
  • Leave additionalProperties open. A field we add next month must not make every answer fail in a client that cached last month's schema.
  • Use plain JSON Schema only: type, properties, required, items, enum and description. No $schema line and no keyword from one draft, so any validator reads it.
ts
const str = { type: "string" };
const num = { type: "number" };
const strOrNull = { type: ["string", "null"] };

function obj(properties: Record<string, JsonSchema>, optional: string[] = []): JsonSchema {
  return {
    type: "object",
    properties,
    required: Object.keys(properties).filter((k) => !optional.includes(k)),
  };
}

const listServices = obj({
  services: {
    type: "array",
    items: obj({ id: str, name: str, description: strOrNull, durationMin: num, priceCents: num }),
  },
});

Only reads declare a schema. A write's answer depends on what it did, and we would rather promise nothing than promise a shape we might break. Writes still return structuredContent, so a client can read it, but with no schema there is nothing to fail against.

The answer goes out twice: once as the JSON text block every client already reads, and once as structuredContent. We build the second by parsing the first, so the two can never disagree. Dates, for example, are strings in both.

ts
export function toolResult(data: unknown, structured: boolean): ToolResult {
  const text = JSON.stringify(data);
  const result: ToolResult = { content: [{ type: "text", text }] };
  if (structured && isPlainObject(data)) result.structuredContent = JSON.parse(text);
  return result;
}

A test seeds a business with something in every corner, empty optional fields included, and calls every read tool. Each answer must fit its schema the way a client's validator reads it.

Tool errors the model can read

Before, every refusal was a JSON-RPC error. Most clients treat that as a failed call and do not show it to the model. So when a time was taken between the availability check and the booking, the model never learned why, and could not offer another time.

Now a tool's own refusal comes back as a normal result with isError set. It carries an error object with a code, a message and any details the tool gave:

ts
// tools/call, for a time someone else booked a moment ago
{
  content: [{ type: "text", text: '{"error":{"code":"BOOKING_REFUSED","message":"That time is no longer available"}}' }],
  structuredContent: { error: { code: "BOOKING_REFUSED", message: "That time is no longer available" } },
  isError: true,
}

The model reads it, checks availability again, and offers the person another time. Nothing was booked twice.

Not every refusal belongs there. A missing scope, a bad credential or a rate limit is for the client software to act on, not the model. Those stay JSON-RPC errors with their HTTP status: 401, 403 or 429. An unknown tool, and arguments that do not parse, stay protocol errors too.

The error that fails its own schema

One detail caught us. A tool with no output schema returns the error in structuredContent as well as in the text. A read tool with an output schema must not. Clients validate any structuredContent against the tool's schema, error or not. An error object does not look like a list of services, so the client would reject the error itself, and the model would see nothing. Those tools send the error in the text only.

ts
export function toolErrorResult(code: string, message: string, details = {}, hasOutputSchema = false): ToolResult {
  const error = { ...details, code, message };
  const result: ToolResult = { content: [{ type: "text", text: JSON.stringify({ error }) }], isError: true };
  if (!hasOutputSchema) result.structuredContent = { error };
  return result;
}

Not breaking anyone

Scripts and integrations written against the old handshake expect a JSON-RPC error for a taken time, and some match on it. Changing that under them would break working code. The protocol gives a clean signal to tell them apart: from 2025-06-18, a client sends an MCP-Protocol-Version header on every request after initialize.

ts
export function wantsToolErrorResults(req: Request): boolean {
  const v = req.headers.get("mcp-protocol-version")?.trim();
  return !!v && SUPPORTED_VERSIONS.includes(v) && v >= "2025-03-26";
}

A caller whose header names a 2025 version gets isError results. A caller with no header gets the JSON-RPC error it always had. Characterization tests pin both.

tools/list changed the same careful way. The new fields are additions. Names, descriptions and input schemas stayed byte for byte the same, and tests that captured them before the change prove it.

What we take from it

  • Send every annotation, true or false. The defaults describe a tool nobody knows, not yours.
  • Derive hints from the tool's definition, and test them against what its description says it does.
  • An output schema is a promise the client enforces by discarding your answer. Promise less.
  • Return a tool's own refusals as isError results with a code, and keep auth and transport failures as protocol errors.
  • Gate new behaviour on the protocol version header, so old callers see no change.
mcpaijson schemaapiengineering

Building on Bookatu?

Bookatu has a public REST API and webhooks. Have a look at the developer docs.

Developer docs