Skip to content

page.mdx

Latest commit

 

History

History
243 lines (175 loc) · 8.33 KB

page.mdx

File metadata and controls

243 lines (175 loc) · 8.33 KB

Call Tool

Clients initiate tool execution by sending a POST request to the /tools/call endpoint. This flow lets clients call a tool and receive its output, with the request and response bodies conforming to the Call Tool Request and Call Tool Response schemas.

Flow Details

Request:

  • Method: POST
  • Endpoint: /tools/call
  • Security: Servers MAY require bearer authentication (JWT). Servers that are internet-facing SHOULD require authentication.
  • Headers:
    • OXP-Version (optional, string): The version 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 schema.

Response (Tool Execution):

  • Status Code: 200 OK
  • Headers:
    • OXP-Version (string): The version of OXP used by the server.
  • Content: A JSON document following the 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

A Tool Server MAY support multiple versions of a given tool, to allow clients to opt-in to new versions while preserving backwards compatibility.

When a client calls a tool using a tool_id that includes a version (e.g. Calculator.Add@1.0.0), the server MUST resolve the version of the tool to call using the following rules:

  1. Default Semantic Versioning: If a tool version is present in the tool ID and is of the form x.y.z where x, y, and z are integers, the server MUST use the exact version specified. For example, Calculator.Add@1.0.0.
  2. Shorthand Versioning: If a tool version is present in the tool ID and is of the form x where x is an integer, the server MUST use the version x.0.0. For example, Calculator.Add@1 which resolves to Calculator.Add@1.0.0.
  3. Implied Latest Version: If no tool version is present in the tool ID, the server MUST use the latest version of the tool.

Error Behavior

Servers MUST differentiate between:

  1. Errors that occur before the tool is called ("Server Errors").
  2. Input validation errors ("Input Validation Errors").
  3. Errors that occur during execution of the tool ("Tool Execution Errors").

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 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 (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 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 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.

If the input parameters are invalid, the server MUST return a 422 response conforming to the Validation Error Response schema. Servers MAY return a parameter_errors object that maps parameter names to error messages.

Tool Execution Errors

If an error occurs during execution of a tool, the server MUST return a 200 response conforming to the Call Tool Response schema, with a success: false and an error object.

Retrying Errors

If can_retry is true, the client SHOULD retry the tool call. If retry_after_ms is present, the client SHOULD wait for the specified number of milliseconds before retrying the tool call.

If additional_prompt_content is present, the client MAY use it to provide additional context to the AI model when prompting it to retry the tool call. For example, the tool may return a list of suggested values that are close to the given input.

Non-Normative Examples

The following examples are non-normative and are provided to illustrate the use of the call tool endpoint.

Successful Execution

Request

POST /call HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "call_id": "123e4567-e89b-12d3-a456-426614174000",
  "tool_id": "Calculator.Add@1.0.0",
  "input": {
    "a": 10,
    "b": 5
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
OXP-Version: 1.0

{
  "call_id": "123e4567-e89b-12d3-a456-426614174000",
  "duration": 2,
  "success": true,
  "value": 15
}

Server Error

In this example, the tool call fails because the tool version is not found.

Request

POST /call HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "call_id": "123e4567-e89b-12d3-a456-426614174000",
  "tool_id": "Calculator.Add@2.0.0"
}

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
OXP-Version: 1.0

{
  "message": "Tool 'Calculator_Add' was not found",
  "developer_message": "Calculator.Add version 2.0.0 is not available"
}

Input Validation Error

In this example, the tool call fails because the second input parameter is not a number. The server catches this before calling the tool, and returns a 422 response with a parameter_errors object that maps the parameter name to an error message.

Request

POST /call HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "call_id": "123e4567-e89b-12d3-a456-426614174000",
  "tool_id": "Calculator.Add@1.0.0",
  "input": {
    "a": 10,
    "b": "infinity"
  }
}

Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
OXP-Version: 1.0

{
  "message": "Some input parameters are invalid",
  "parameter_errors": {
    "b": "Must be a number"
  }
}

Tool Execution Error

In this example, the tool call fails because the doorbell ID is not found. The tool opts to send back information to the client to help it retry the tool call.

Request

POST /call HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "call_id": "723e4567-e89b-12d3-a456-426614174006",
  "tool_id": "Doorbell.Ring@0.1.0",
  "input": {
    "doorbell_id": "doorbell1"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
OXP-Version: 1.0

{
  "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
  }
}