Tool schemas

OpenAPI for tools.

OpenAPI tells Orchet which operations are callable tools, what arguments are valid, which credentials are needed, and whether user confirmation is required.

Tool requirements.

Every operation Orchet can call must be marked with x-orchet-tool: true and must expose an object-shaped input schema.

Use a stable operationId. It becomes the tool name in the planner and event logs.
Write a summary and description in plain user language, not provider jargon.
Use JSON Schema required fields, enums, min/max values, and descriptions wherever the provider API has constraints.
Return structured JSON so Orchet can render cards, receipts, confirmations, and follow-up actions.

x-orchet metadata.

The SDK and registry understand these extensions. They are reviewable product contracts, not comments.

Extension	Meaning
x-orchet-tool	true exposes the operation to Orchet.
x-orchet-requires-confirmation	false or a structured confirmation type.
x-orchet-pii-required	PII fields needed for this tool call.
x-orchet-intent-tags	Routing hints for planner selection.
x-orchet-cancels / x-orchet-cancel-for	Rollback pair for tools that create bookings, orders, or other obligations.
x-orchet-compensation-*	Durable mission rollback behavior.

Side-effect tools need rollback.

A tool that creates a booking, order, reservation, expense, or other user-visible obligation must declare a cancel counterpart in the same OpenAPI document.

YAML

paths:
  /book:
    post:
      operationId: flight_book_offer
      summary: Book a selected flight offer.
      x-orchet-tool: true
      x-orchet-requires-confirmation: structured-itinerary
      x-orchet-cancels: flight_cancel_booking
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [offer_id, traveler_id]
              properties:
                offer_id:
                  type: string
                traveler_id:
                  type: string
  /cancel:
    post:
      operationId: flight_cancel_booking
      x-orchet-tool: true
      x-orchet-cancel-for: flight_book_offer
      x-orchet-requires-confirmation: false

Cancel tools do not ask again.

Rollback can run after another leg in a multi-agent mission fails. A second human prompt would deadlock the recovery path.