maintenance_request_create

Create maintenance request. Submits a maintenance request, the same way the person would in PorchQ.

Who can use it: Everyone in the community.

Scope	Effect	Hints
maintenance:write	write	changes data

Description shown to assistants

Use this when the user asks to submit a new maintenance request.

Arguments

Argument	Type	Required	About
property_id	string	No	The community’s public id (prop_web…). Pass it on every call.
title	string	Yes	A short title for the request.
description	string	No	What is wrong, in the person’s words.
priority	string	No	urgent, high, medium or low.
idempotency_key	string	No	Optional. A unique value for this change; sending the same value again does nothing twice. At most 200 characters.

What it returns

Every result has content (one short sentence for the person) and structuredContent (the data below). A tool that could not run answers with isError: true and a sentence saying why; see Errors and limits.

• property: the community.
• maintenance_request: the new request, with the same fields as in maintenance_requests_list.

structuredContent follows this JSON Schema, also in tools/list as outputSchema:

{
  "type": "object",
  "properties": {
    "property": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "addressLine1": { "type": ["string", "null"] },
        "addressLine2": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "state": { "type": ["string", "null"] },
        "postalCode": { "type": ["string", "null"] },
        "timezone": { "type": ["string", "null"] },
        "billingFrequency": { "type": ["string", "null"] },
        "demoClone": { "type": "boolean" },
        "demoPersona": { "type": ["string", "null"] },
        "demoExpiresAt": { "type": ["string", "null"] }
      },
      "required": ["id", "name"]
    },
    "maintenance_request": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "status": { "type": "string" },
        "priority": { "type": "string" },
        "submittedAt": { "type": ["string", "null"] },
        "updatedAt": { "type": ["string", "null"] },
        "requester": { "type": ["string", "null"] },
        "assignedTo": { "type": ["string", "null"] },
        "summary": { "type": ["string", "null"] },
        "tags": { "type": "array", "items": { "type": "string" } },
        "category": { "type": ["string", "null"] },
        "residentNotes": { "type": ["string", "null"] },
        "slaDueAt": { "type": ["string", "null"] },
        "submittedByResident": { "type": "boolean" },
        "vendorId": { "type": ["string", "null"] },
        "vendorName": { "type": ["string", "null"] }
      },
      "required": ["id", "title", "status", "priority"]
    }
  },
  "required": ["property", "maintenance_request"]
}

Notes

• A resident’s request is submitted in their name, exactly as from the resident portal: the community’s staff are notified by email, text and push, and the resident’s message thread about it opens.
• A request an owner or manager logs follows the staff form: description becomes the summary and the person is the requester.
• priority is urgent, high, medium or low; anything else is saved as medium.
• The request records that it came through MCP and the name of the app.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "maintenance_request_create",
    "arguments": {
      "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d",
      "title": "Hallway light out on the 3rd floor",
      "description": "The light by unit 312 has been out since Monday.",
      "priority": "medium",
      "idempotency_key": "6f1c2a9e-0d3b-4c1e-9a77-2b5d8e4f1a03"
    }
  }
}