pearl-api-mcp-server

Use this when the user wants a rapid AI-generated answer, draft, or alternative perspective on a low-risk or exploratory topic that does not require human validation. Do not use for medical, legal, financial, or safety-critical questions — use askExpert or askPearlExpert instead.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The user's question"
    },
    "chatHistory": {
      "description": "Optional conversation history. This ensures experts see the complete context",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "role",
          "content"
        ]
      }
    },
    "sessionId": {
      "description": "Optional session ID for continuing a conversation",
      "type": "string"
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use this when the problem is complex, ambiguous, high-stakes, or multidisciplinary and would benefit from AI intake followed by escalation to a human expert. Do not use for simple fact queries (use askPearlAi) or when the user explicitly requests a human directly (use askExpert). Supports phone callback — pass phoneNumber and contactPreference='phone' if the user wants a call.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The user's question"
    },
    "chatHistory": {
      "description": "Optional conversation history. This ensures experts see the complete context",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "role",
          "content"
        ]
      }
    },
    "sessionId": {
      "description": "Optional session ID for continuing a conversation",
      "type": "string"
    },
    "phoneNumber": {
      "description": "Customer's phone number for expert callback in E.164 format (e.g., +15551234567). Only pass when the user explicitly provides it.",
      "type": "string"
    },
    "contactPreference": {
      "description": "Customer's preferred contact method. Set to 'phone' when the user wants a phone callback.",
      "type": "string",
      "enum": [
        "chat",
        "phone"
      ]
    },
    "enableMockResponse": {
      "description": "When true, the API returns a hardcoded mock expert success response instead of routing to a real expert. Useful for testing downstream behavior.",
      "type": "boolean"
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use this when the user explicitly asks to speak with a real human expert, needs personalized advice in a complex or sensitive domain, or says something like 'Can I talk to a real expert?'. Supports phone callback — pass phoneNumber and contactPreference='phone' if the user wants a call.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The user's question"
    },
    "chatHistory": {
      "description": "Optional conversation history. This ensures experts see the complete context",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "role",
          "content"
        ]
      }
    },
    "sessionId": {
      "description": "Optional session ID for continuing a conversation",
      "type": "string"
    },
    "phoneNumber": {
      "description": "Customer's phone number for expert callback in E.164 format (e.g., +15551234567). Only pass when the user explicitly provides it.",
      "type": "string"
    },
    "contactPreference": {
      "description": "Customer's preferred contact method. Set to 'phone' when the user wants a phone callback.",
      "type": "string",
      "enum": [
        "chat",
        "phone"
      ]
    },
    "enableMockResponse": {
      "description": "When true, the API returns a hardcoded mock expert success response instead of routing to a real expert. Useful for testing downstream behavior.",
      "type": "boolean"
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use this when a professional needs to validate the correctness, safety, or trustworthiness of a specific AI-generated answer, or when the user asks to have an answer double-checked by a real expert.

{
  "type": "object",
  "properties": {
    "answer": {
      "type": "string",
      "minLength": 1,
      "description": "The AI-generated answer that requires human verification"
    },
    "chatHistory": {
      "description": "Optional prior messages for context (ordered, oldest first)",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ],
            "description": "Message role"
          },
          "content": {
            "type": "string",
            "description": "Message content"
          }
        },
        "required": [
          "role",
          "content"
        ]
      }
    },
    "sessionId": {
      "description": "Existing session ID to continue; generated if omitted",
      "type": "string"
    },
    "enableMockResponse": {
      "description": "When true, the API returns a hardcoded mock expert success response instead of routing to a real expert. Useful for testing downstream behavior.",
      "type": "boolean"
    }
  },
  "required": [
    "answer"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Retrieve the full message history for a session. Includes all messages (after any formatting done during processing). Use to resume discussions.

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The session ID of the conversation"
    }
  },
  "required": [
    "sessionId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use this tool only when the user explicitly requests to start verification, fact-checking, or expert validation of an AI-generated answer. This tool must be used exclusively to initiate the verification process. Do not call it to check status, retrieve results, or for any follow-up actions. A human Pearl expert will review the answer and determine its correctness. Only one verification is allowed per chat session — this tool must not be invoked more than once. Invoking this tool renders an interactive UI component that displays live verification status and the final expert verdict.

{
  "type": "object",
  "properties": {
    "conversation": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant"
            ],
            "description": "The role of the participant in the conversation (e.g. \"user\" or \"assistant\")."
          },
          "content": {
            "type": "string",
            "description": "The message content sent by the participant."
          }
        },
        "required": [
          "role",
          "content"
        ]
      },
      "description": "Full conversation between the user and the AI assistant to be reviewed by a human expert. Must contain at least one assistant message — the AI-generated answer that will be assessed."
    },
    "questionCategory": {
      "type": "string",
      "enum": [
        "Car",
        "Veterinary",
        "Health",
        "Tech",
        "Law",
        "Other"
      ],
      "description": "The category that best describes the question being verified.\n- \"Car\" for automotive/vehicle topics\n- \"Veterinary\" for pet or animal health\n- \"Health\" for human medical topics\n- \"Tech\" for technology/software\n- \"Law\" for legal questions\n- \"Other\" for anything that does not fit the above"
    }
  },
  "required": [
    "conversation",
    "questionCategory"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Indicates whether the answer was successfully submitted for expert verification."
    },
    "category": {
      "type": "string",
      "enum": [
        "Car",
        "Veterinary",
        "Health",
        "Tech",
        "Law",
        "Other"
      ],
      "description": "The category that best describes the question being verified.\n- \"Car\" for automotive/vehicle topics\n- \"Veterinary\" for pet or animal health\n- \"Health\" for human medical topics\n- \"Tech\" for technology/software\n- \"Law\" for legal questions\n- \"Other\" for anything that does not fit the above"
    },
    "sessionId": {
      "type": "string",
      "description": "The session identifier of the verification. Used for tracking and retrieval of the verification state."
    },
    "error": {
      "description": "Error if the answer could not be submitted for verification.",
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Error message if the answer could not be submitted for verification."
        },
        "code": {
          "type": "string",
          "enum": [
            "no_messages_to_verify",
            "session_already_verified",
            "unknown_error"
          ],
          "description": "Error code if the answer could not be submitted for verification."
        }
      },
      "required": [
        "message",
        "code"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "success",
    "category",
    "sessionId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when polling the current status of a verification request previously submitted via send_answer_for_verification. Returns the verification state (not started, in progress, or completed) and the expert's verdict once the review is complete.

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The session identifier of the chat whose verification state should be retrieved. Must match the sessionId previously returned by send_answer_for_verification."
    }
  },
  "required": [
    "sessionId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Indicates whether the verification status was successfully retrieved."
    },
    "status": {
      "type": "string",
      "enum": [
        "NotStarted",
        "InProgress",
        "Completed",
        "Error"
      ],
      "description": "Indicates the current status of the chat verification process."
    },
    "isAnswerCorrect": {
      "description": "Indicates whether the AI-generated answer is fully correct as rated by the human expert.",
      "type": "boolean"
    },
    "expertProfile": {
      "description": "Information about the human expert who verified the answer.",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the human expert who verified the answer."
        },
        "title": {
          "description": "Title or job description of the human expert who verified the answer.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "avatarUrl": {
          "description": "URL of the avatar image of the human expert who verified the answer.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "rating": {
          "description": "Rating of the human expert who verified the answer.",
          "type": "number"
        },
        "totalNumberOfRatings": {
          "description": "Total number of ratings of the human expert who verified the answer.",
          "type": "number"
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "success",
    "status"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}