Output Structure

Output Format Metadata

{
  "OutputFormat": "structured",  // "structured" or "unstructured"
  "OutputType": "json",          // "json", "text", etc.
  "type": "api_response",        // Response type identifier
  // ...other fields depend on the response type
}

These fields help clients understand how to parse and process the response:

• OutputFormat: Indicates whether the response has a structured format (JSON) or unstructured format (plain text)
• OutputType: Specifies the content type of the response
• type: Identifies the specific type of response (e.g., "api_response", "error", "confirmation_request")

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "api_response",
  "data": {
    // API-specific response data
  },
  "metadata": {
    "status_code": 200,
    "headers": {
      // Response headers from the API
    }
  }
}

The data field contains the actual API response, which varies depending on the operation. The metadata field provides information about the HTTP response, including status code and headers.

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "error",
  "error": {
    "code": "validation_error",
    "message": "Invalid parameter",
    "details": {
      "field": "name",
      "reason": "required field missing"
    },
    "suggestions": [
      "Provide a name parameter"
    ]
  }
}

The error response includes:

• code: A machine-readable error code
• message: A human-readable error message
• details: Additional information about the error
• suggestions: Recommended actions to resolve the error

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "confirmation_request",
  "confirmation_required": true,
  "message": "This action is irreversible. Proceed?",
  "action": "delete_resource"
}

The confirmation request includes:

• confirmation_required: Always true for confirmation requests
• message: A human-readable description of the action requiring confirmation
• action: A machine-readable identifier for the type of action

To proceed with the operation, retry the call with the __confirmed parameter set to true:

{
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "__confirmed": true
}

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "api_response",
  "data": {
    // Partial response data
  },
  "partial": true,
  "resume_token": "abc123xyz789",
  "metadata": {
    "status_code": 200,
    "headers": {
      // Response headers
    }
  }
}

Partial responses include:

• partial: Set to true to indicate that this is a partial response
• resume_token: A token that can be used to retrieve the next chunk of data

To retrieve the next chunk, make a new call with the resume_token:

{
  "resume_token": "abc123xyz789"
}

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "api_docs",
  "tools": [
    {
      "name": "listServices",
      "description": "Retrieves a list of all services configured in the user's account.",
      "inputSchema": {
        "type": "object",
        "properties": {
          // Input parameter definitions
        },
        "required": []
      },
      "outputSchema": {
        "type": "array",
        "items": {
          // Output structure definition
        }
      },
      "examples": [
        {
          "input": {},
          "output": {
            // Example output
          }
        }
      ]
    },
    // Other tools...
  ]
}

This response provides machine-readable documentation that clients can use to understand:

• What tools are available
• What parameters each tool accepts
• What output format to expect
• Example inputs and outputs

JavaScript

async function callTool(name, args) {
  const response = await fetch('http://localhost:8080/jsonrpc', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: { name, arguments: args }
    })
  });
  
  const result = await response.json();
  
  // Check for error
  if (result.error) {
    throw new Error(`RPC error: ${result.error.message}`);
  }
  
  // Process the result based on its type
  switch (result.result.type) {
    case 'api_response':
      return result.result.data;
      
    case 'error':
      throw new Error(`API error: ${result.result.error.message}`);
      
    case 'confirmation_request':
      const confirmed = confirm(result.result.message);
      if (confirmed) {
        return callTool(name, { ...args, __confirmed: true });
      } else {
        throw new Error('Operation cancelled');
      }
      
    default:
      console.warn(`Unknown response type: ${result.result.type}`);
      return result.result;
  }
}

Python

import requests
import json

def call_tool(name, args):
    response = requests.post('http://localhost:8080/jsonrpc', json={
        'jsonrpc': '2.0',
        'id': 1,
        'method': 'tools/call',
        'params': {'name': name, 'arguments': args}
    })
    
    result = response.json()
    
    # Check for JSON-RPC error
    if 'error' in result:
        raise Exception(f"RPC error: {result['error']['message']}")
    
    # Process the result based on its type
    result_obj = result['result']
    
    if result_obj['type'] == 'api_response':
        return result_obj['data']
        
    elif result_obj['type'] == 'error':
        error = result_obj['error']
        raise Exception(f"API error: {error['message']} ({error['code']})")
        
    elif result_obj['type'] == 'confirmation_request':
        # In a real application, you might prompt the user
        confirmed = input(f"{result_obj['message']} (y/n): ").lower() == 'y'
        
        if confirmed:
            args['__confirmed'] = True
            return call_tool(name, args)
        else:
            raise Exception("Operation cancelled")
            
    else:
        print(f"Warning: Unknown response type: {result_obj['type']}")
        return result_obj