OpenExecProtocol · nbarbettini · Mar 17, 2025
diff --git a/app/page.mdx b/app/page.mdx
@@ -12,7 +12,7 @@ We envision a world in which agents can discover and interact with thousands upo
 
 ## What is OXP?
 
-The Open eXecution Protocol is a [standardized protocol](https://github.com/OpenToolCalling/Specification/tree/main/spec/http/1.0/openapi.json) that enables AI agents to discover and interact with external tools in a consistent, reliable way. It establishes a structured communication framework between agents (clients) and tools (functions or services), creating a unified language for tool definitions, requests, and responses.
+The Open eXecution Protocol is a [specification](https://github.com/OpenToolCalling/Specification/tree/main/spec/http/1.0/openapi.json) that enables AI agents to discover and interact with external tools in a consistent, reliable way. It establishes a structured communication framework between agents (clients) and tools (functions or services), creating a unified language for tool definitions, requests, and responses.
 
 At its core, OXP provides:
 

diff --git a/app/spec-1.0/protocol/call-tool/page.mdx b/app/spec-1.0/protocol/call-tool/page.mdx
@@ -10,23 +10,31 @@ This flow lets clients call a tool and receive its output, with the request and
 - **Method:** POST
 - **Endpoint:** `/tools/call`
 - **Security:** Servers MAY require bearer authentication (JWT). Servers that are internet-facing SHOULD require authentication.
-- **Payload:** A JSON document containing:
-  - **`$schema` Field** (optional): The client MAY include a `$schema` field in the request body to indicate the version of OXP that the client supports. If the `$schema` field is not included, the server MUST assume the client supports the latest version of OXP.
-  - **`request` Object:** A JSON document following the [Call Tool Request](../schemas/call-tool-request) schema.
+- **Headers:**
+  - `OXP-Version` (optional, string): The [version](../versioning) of OXP that the client supports. If not provided, the server MAY assume the client supports the latest version of OXP.
+- **Payload:** A JSON document following the [Call Tool Request](../schemas/call-tool-request) schema.
 
 **Response (Tool Execution):**
 
 - **Status Code:** 200 OK
-- **Content:** A JSON document following the [Call Tool Response](../schemas/call-tool-response) schema. The server MUST return a 200 response even if the tool call fails.
+- **Headers:**
+  - `OXP-Version` (string): The [version](../versioning) of OXP used by the server.
+- **Content:** A JSON document following the [Call Tool Response](../schemas/call-tool-response) schema.
+
+The server MUST return a 200 response, even if the tool call encounters an error.
 
 **Response (Server Error):**
 
 - **Status Code:** 400
+- **Headers:**
+  - `OXP-Version` (string): The version of OXP used by the server.
 - **Content:** A JSON document following the `ServerErrorResponse` schema.
 
 **Response (Input Validation Error):**
 
 - **Status Code:** 422
+- **Headers:**
+  - `OXP-Version` (string): The version of OXP used by the server.
 - **Content:** A JSON document following the `ValidationErrorResponse` schema.
 
 ## Tool Version Resolution
@@ -49,16 +57,26 @@ Servers MUST differentiate between:
 
 ### Server Errors
 
-If an error occurs before the tool is called that is not related to input validation, the server MUST return a 400 response conforming to the [Server Error Response](../schemas/errors#servererrorresponse) schema. Examples of such errors include:
+If an error occurs before the tool is called that is not related to input validation, the server MUST return a 400 response conforming to the [Server Error Response](../schemas/errors#server-error-response) schema. Examples of such errors include:
 
 - The tool server is temporarily unavailable.
 - The requested version of OXP is not supported.
 - The requested tool ID is invalid or cannot be found.
 - The requested tool version is not available.
-- The tool server requires authentication, but the client did not provide valid credentials.
+- The tool server requires authentication, but the client did not provide valid credentials (see below, Tool Authorization Challenges).
 
 The `message` field MUST be present and SHOULD be a user-facing error message. The `developer_message` field MAY be present and SHOULD be an internal message that can be logged but will not be shown to the user or an AI model.
 
+### Tool Authorization Challenges
+
+If a tool requires authorization that has not been completed, the server MUST return a 400 response conforming to the Server Error Response's [Tool Authorization Challenge](../schemas/errors#tool-authorization-challenge) schema, with a `missing_requirements.authorization` array.
+
+The client SHOULD display the `url` to the user to complete the authorization challenge.
+
+The client MAY poll the `check_url` to check the status of the authorization challenge. The `check_url` endpoint MUST return a 200 response containing a JSON document conforming to the [Authorization Challenge Check Response](../schemas/errors#authorization-challenge-check-response) schema.
+
+If the challenge is completed, the client MAY retry the tool call.
+
 ### Input Validation Errors
 
 When a valid tool ID and version are provided, servers MUST validate the input parameters against the tool's `input_schema` before calling the tool.
@@ -86,18 +104,15 @@ The following examples are non-normative and are provided to illustrate the use
 ```http
 POST /call HTTP/1.1
 Host: api.example.com
-Content-Type: application/json
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
 
 {
-  "$schema": "urn:oxp:1.0",
-  "request": {
-    "call_id": "123e4567-e89b-12d3-a456-426614174000",
-    "tool_id": "[email protected]",
-    "input": {
-      "a": 10,
-      "b": 5
-    }
+  "call_id": "123e4567-e89b-12d3-a456-426614174000",
+  "tool_id": "[email protected]",
+  "input": {
+    "a": 10,
+    "b": 5
   }
 }
 ```
@@ -107,15 +122,13 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 ```http
 HTTP/1.1 200 OK
 Content-Type: application/json
+OXP-Version: 1.0
 
 {
-  "$schema": "urn:oxp:1.0",
-  "result": {
-    "call_id": "123e4567-e89b-12d3-a456-426614174000",
-    "duration": 2,
-    "success": true,
-    "value": 15
-  }
+  "call_id": "123e4567-e89b-12d3-a456-426614174000",
+  "duration": 2,
+  "success": true,
+  "value": 15
 }
 ```
 
@@ -128,15 +141,12 @@ In this example, the tool call fails because the tool version is not found.
 ```http
 POST /call HTTP/1.1
 Host: api.example.com
-Content-Type: application/json
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
 
 {
-  "$schema": "urn:oxp:1.0",
-  "request": {
-    "call_id": "123e4567-e89b-12d3-a456-426614174000",
-    "tool_id": "[email protected]"
-  }
+  "call_id": "123e4567-e89b-12d3-a456-426614174000",
+  "tool_id": "[email protected]"
 }
 ```
 
@@ -145,9 +155,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 ```http
 HTTP/1.1 400 Bad Request
 Content-Type: application/json
+OXP-Version: 1.0
 
 {
-  "$schema": "urn:oxp:1.0",
   "message": "Tool 'Calculator_Add' was not found",
   "developer_message": "Calculator.Add version 2.0.0 is not available"
 }
@@ -162,18 +172,15 @@ In this example, the tool call fails because the second input parameter is not a
 ```http
 POST /call HTTP/1.1
 Host: api.example.com
-Content-Type: application/json
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
 
 {
-  "$schema": "urn:oxp:1.0",
-  "request": {
-    "call_id": "123e4567-e89b-12d3-a456-426614174000",
-    "tool_id": "[email protected]",
-    "input": {
-      "a": 10,
-      "b": "infinity"
-    }
+  "call_id": "123e4567-e89b-12d3-a456-426614174000",
+  "tool_id": "[email protected]",
+  "input": {
+    "a": 10,
+    "b": "infinity"
   }
 }
 ```
@@ -183,9 +190,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 ```http
 HTTP/1.1 422 Unprocessable Entity
 Content-Type: application/json
+OXP-Version: 1.0
 
 {
-  "$schema": "urn:oxp:1.0",
   "message": "Some input parameters are invalid",
   "parameter_errors": {
     "b": "Must be a number"
@@ -202,17 +209,14 @@ In this example, the tool call fails because the doorbell ID is not found. The t
 ```http
 POST /call HTTP/1.1
 Host: api.example.com
-Content-Type: application/json
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
 
 {
-  "$schema": "urn:oxp:1.0",
-  "request": {
-    "call_id": "723e4567-e89b-12d3-a456-426614174006",
-    "tool_id": "[email protected]",
-    "input": {
-      "doorbell_id": "doorbell1"
-    }
+  "call_id": "723e4567-e89b-12d3-a456-426614174006",
+  "tool_id": "[email protected]",
+  "input": {
+    "doorbell_id": "doorbell1"
   }
 }
 ```
@@ -222,20 +226,18 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 ```http
 HTTP/1.1 200 OK
 Content-Type: application/json
+OXP-Version: 1.0
 
 {
-  "$schema": "urn:oxp:1.0",
-  "result": {
-     "call_id": "723e4567-e89b-12d3-a456-426614174006",
-     "duration": 60,
-     "success": false,
-     "error": {
-       "message": "Doorbell ID not found",
-       "developer_message": "The doorbell with ID 'doorbell1' does not exist.",
-       "can_retry": true,
-       "additional_prompt_content": "ids: doorbell42,doorbell84",
-       "retry_after_ms": 500
-     }
-   }
+  "call_id": "723e4567-e89b-12d3-a456-426614174006",
+  "duration": 60,
+  "success": false,
+  "error": {
+    "message": "Doorbell ID not found",
+    "developer_message": "The doorbell with ID 'doorbell1' does not exist.",
+    "can_retry": true,
+    "additional_prompt_content": "ids: doorbell42,doorbell84",
+    "retry_after_ms": 500
+  }
 }
 ```
diff --git a/app/spec-1.0/protocol/health-check/page.mdx b/app/spec-1.0/protocol/health-check/page.mdx
@@ -9,10 +9,14 @@ An OXP server MUST implement a health check endpoint that returns a 200 OK respo
 - **Method:** GET
 - **Endpoint:** `/health`
 - **Security:** No authentication is required.
+- **Headers:**
+  - `OXP-Version` (optional, string): The [version](../versioning) of OXP that the client supports. If not provided, the server MAY assume the client supports the latest version of OXP.
 
 **Response:**
 
 - **Status Code:** 200 OK
+- **Headers:**
+  - `OXP-Version` (string): The [version](../versioning) of OXP used by the server.
 
 If the server is ready to receive tool calls, the server MUST return a 200 OK response. The server MAY return an HTTP 503 response if it is not ready to receive tool calls.
 
@@ -30,4 +34,5 @@ GET /health HTTP/1.1
 
 ```http
 HTTP/1.1 200 OK
+OXP-Version: 1.0
 ```
diff --git a/app/spec-1.0/protocol/list-tools/page.mdx b/app/spec-1.0/protocol/list-tools/page.mdx
@@ -1,6 +1,6 @@
 # List Tools
 
-Clients perform tool discovery by retrieving tool definitions from the Tool Server using the `/tools` endpoint. This protocol provides a catalog of tools that the client can use, all of which conform to the [`ToolDefinition` schema](../schemas/tool-definition).
+Clients perform tool discovery by retrieving tool definitions from the Tool Server using the `/tools` endpoint. This protocol provides a catalog of tools that the client can use, all of which conform to the [Tool Definition schema](../schemas/tool-definition).
 
 ## Flow Details
 
@@ -9,13 +9,15 @@ Clients perform tool discovery by retrieving tool definitions from the Tool Serv
 - **Method:** GET
 - **Endpoint:** `/tools`
 - **Security:** Servers MAY require bearer authentication (JWT). Servers that are internet-facing SHOULD require authentication.
-- **Payload:** A JSON document containing:
-  - **`$schema` Field** (optional): The client MAY include a `$schema` field in the request body to indicate the version of OXP that the client supports. If the `$schema` field is not included, the server MUST assume the client supports the latest version of OXP.
+- **Headers:**
+  - `OXP-Version` (optional, string): The [version](../versioning) of OXP that the client supports. If not provided, the server MAY assume the client supports the latest version of OXP.
 
 **Response:**
 
 - **Status Code:** 200 OK
-  - **Content:** A JSON object that includes a `$schema` URI reference (indicating the [OXP version](../versioning)) and a `tools` array. Each element in the array is a complete [Tool Definition](../schemas/tool-definition). If there are no tools available, the `tools` array MUST be empty.
+- **Headers:**
+  - `OXP-Version` (string): The [version](../versioning) of OXP used by the server.
+- **Content:** A JSON document containing an `items` array of [Tool Definitions](../schemas/tool-definition). If there are no tools available, the `items` array MUST be empty.
 
 ## Non-Normative Example
 
@@ -31,39 +33,43 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
 **Response (No Tools)**
 
-```json
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+OXP-Version: 1.0
+
 {
-  "$schema": "urn:oxp:1.0",
-  "tools": []
+  "items": []
 }
 ```
 
 **Response (With Tools)**
 
-```json
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+OXP-Version: 1.0
+
 {
-  "$schema": "urn:oxp:1.0",
-  "tools": [
+  "items": [
     {
       "id": "[email protected]",
       "name": "Calculator_Add",
       "description": "Adds two numbers together.",
       "version": "1.0.0",
       "input_schema": {
-        "parameters": {
-          "type": "object",
-          "properties": {
-            "a": {
-              "type": "number",
-              "description": "The first number to add."
-            },
-            "b": {
-              "type": "number",
-              "description": "The second number to add."
-            }
+        "type": "object",
+        "properties": {
+          "a": {
+            "type": "number",
+            "description": "The first number to add."
           },
-          "required": ["a", "b"]
-        }
+          "b": {
+            "type": "number",
+            "description": "The second number to add."
+          }
+        },
+        "required": ["a", "b"]
       },
       "output_schema": {
         "type": "number",
@@ -76,16 +82,14 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
       "description": "Rings a doorbell given a doorbell ID.",
       "version": "0.1.0",
       "input_schema": {
-        "parameters": {
-          "type": "object",
-          "properties": {
-            "doorbell_id": {
-              "type": "string",
-              "description": "The ID of the doorbell to ring."
-            }
-          },
-          "required": ["doorbell_id"]
-        }
+        "type": "object",
+        "properties": {
+          "doorbell_id": {
+            "type": "string",
+            "description": "The ID of the doorbell to ring."
+          }
+        },
+        "required": ["doorbell_id"]
       },
       "output_schema": null
     }