get_signing_ceremony_handoff

Get document signing handoff

Check where a legal document that needs the buyer's signature stands and get the exact Ohvii surface to sign it: a counter response, a contingency removal (one contingencyId, a contingencyIds set the buyer named for one form covering several, or allRemaining when they chose to clear every one left; never bundle a contingency the buyer has not decided on), a repair request, an addendum, a cancellation, a verification of property, a buyer visual inspection, or document_signing for PDFs the buyer or the listing side added (name the documentIds to start a package or the packageId to resume one; only such a signed package is delivered through create_signed_documents_delivery_draft, every other signed form through its own email draft). Returns the product's eligibility for that action, the signing tasks and their state, the ids of already signed files, and a ceremonyUrl that opens exactly that flow. Hand the buyer the URL for the returned next step. For a reviewed accept_all repair response, next is confirm_agreement: the buyer chooses Confirm agreement on Ohvii, with no additional signature or signed acceptance document, unless the seller answered on their own form with a line for the buyer to sign (buyerAcceptanceLine true on get_repair_request): then the buyer signs that form in the signing room. A recorded confirmation returns complete; any confirmation email still needs separate buyer approval. When next is deliver_signed_document, send the signed file with the email tools. On a saved home (before the offer is signed) only document_signing is available, for a PDF the listing side or the buyer added that must be signed before any offer, such as a public-report receipt in a developer sale; every other ceremony belongs to a signed offer. A not_available or rights_uncertain result is a stop, not something to work around.

Effect: Read
Required scopes: workspace:read
Workflow stages: closing, offer, transaction
Data classes: documents, signing
Operation cost: 1 weighted units; additional domain limits may apply.
Configurations: Standard, Buyer UI v2
Muse proposal: Read. Retrieves or computes authorized information; consult the tool contract for its scopes and result. Meta makes the final classification during review.

Buyer approval and signing controls apply in addition to the scopes above. Read error and retry guidance before implementing recovery.

Input and output contracts

Returns structured content and a JSON text content block. Live discovery may compact a large output schema; execution validates the full contract below.

Input fields

Required applies within the containing object. Optional fields can be omitted; null is accepted only where listed. Field descriptions and constraints come from the source schema. The raw schema remains the complete contract.

Field Required Meaning and constraints

ceremonyobject

Yes

Must match exactly one alternative.

ceremony: nested contract

Alternative 1: kind = "addendum"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`draftId`string	No	Pattern validation applies; see the raw schema.
`kind`string	Yes	Must be "addendum".

Alternative 2: kind = "buyer_visual_inspection"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`kind`string	Yes	Must be "buyer_visual_inspection".

Alternative 3: kind = "cancellation"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`kind`string	Yes	Must be "cancellation".

Alternative 4: kind = "contingency_removal"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`allRemaining`boolean	No	No additional description in the contract.
`contingencyId`string	No	Allowed: "inspection", "appraisal", "loan", "hoa", "sale-of-home".
`contingencyIds`array<string>	No	Minimum items: 1. Maximum items: 5.
contingencyIds: nested contract Array item contract Allowed: "inspection", "appraisal", "loan", "hoa", "sale-of-home".
`kind`string	Yes	Must be "contingency_removal".

Alternative 5: kind = "counter_response"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`draftId`string	No	Pattern validation applies; see the raw schema.
`kind`string	Yes	Must be "counter_response".

Alternative 6: kind = "document_signing"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`documentIds`array<string>	No	Minimum items: 1. Maximum items: 100.
documentIds: nested contract Array item contract Pattern validation applies; see the raw schema.
`kind`string	Yes	Must be "document_signing".
`packageId`string	No	Pattern validation applies; see the raw schema.

Alternative 7: kind = "repair_request"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`draftId`string	No	Pattern validation applies; see the raw schema.
`kind`string	Yes	Must be "repair_request".

Alternative 8: kind = "verification"

Extra fields are not allowed.

Field	Required	Meaning and constraints
`draftId`string	No	Pattern validation applies; see the raw schema.
`kind`string	Yes	Must be "verification".

workspaceIdstring

Yes

Pattern validation applies; see the raw schema.

Output fields

Field Required Meaning and constraints

ceremonyUrlstring | null

Yes

Must match at least one alternative.

ceremonyUrl: nested contract

Alternative 1: string

Format: uri. Maximum characters: 2048.

Alternative 2: null

eligibilityobject

Yes

Extra fields are not allowed.

eligibility: nested contract

Field	Required	Meaning and constraints
`reason`string	Yes	Allowed: "ELIGIBLE", "ALREADY_IN_PROGRESS", "ALREADY_RATIFIED", "CONTINGENCY_DEADLINE_UNRESOLVED", "CONTINGENCY_REMOVED", "CONTINGENCY_WAIVED", "MISSING_CONTRACT_DATE", "NOT_OPEN_CONTRACT", "RATIFICATION_NOT_PENDING", "TERMINAL_TRANSACTION".
`state`string	Yes	Allowed: "eligible", "eligible_after_confirmation", "already_in_progress", "rights_uncertain", "unavailable".

kindstring

Yes

Allowed: "addendum", "buyer_visual_inspection", "cancellation", "contingency_removal", "counter_response", "document_signing", "repair_request", "verification".

nextstring

Yes

Allowed: "not_available", "open_ceremony", "confirm_agreement", "awaiting_co_buyer", "deliver_signed_document", "complete".

reasonsarray<string>

Yes

Maximum items: 10.

reasons: nested contract

Array item contract

Minimum characters: 1. Maximum characters: 300.

schemaVersionstring

Yes

Must be "1".

signedDocumentIdsarray<string>

Yes

Maximum items: 20.

signedDocumentIds: nested contract

Array item contract

Pattern validation applies; see the raw schema.

tasksarray<object>

Yes

Maximum items: 20.

tasks: nested contract

Array item contract

Extra fields are not allowed.

Field	Required	Meaning and constraints
`actionLabel`string	Yes	Minimum characters: 1. Maximum characters: 120.
`documentIds`array<string>	Yes	Maximum items: 20.
documentIds: nested contract Array item contract Pattern validation applies; see the raw schema.
`id`string	Yes	Must match at least one alternative.
id: nested contract Alternative 1: string Pattern validation applies; see the raw schema. Alternative 2: string Minimum characters: 1. Maximum characters: 400.
`packageId`string \| null	Yes	Must match at least one alternative.
packageId: nested contract Alternative 1: string Pattern validation applies; see the raw schema. Alternative 2: null
`status`string	Yes	Allowed: "needs_action", "waiting", "completed".
`title`string	Yes	Minimum characters: 1. Maximum characters: 200.
`updatedAt`string \| null	Yes	Must match at least one alternative.
updatedAt: nested contract Alternative 1: string Format: date-time. Pattern validation applies; see the raw schema. Alternative 2: null

workspaceIdstring

Yes

Pattern validation applies; see the raw schema.

Raw input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ceremony": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "draftId": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "kind": {
              "type": "string",
              "const": "addendum"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "buyer_visual_inspection"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "cancellation"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "allRemaining": {
              "type": "boolean"
            },
            "contingencyId": {
              "type": "string",
              "enum": [
                "inspection",
                "appraisal",
                "loan",
                "hoa",
                "sale-of-home"
              ]
            },
            "contingencyIds": {
              "minItems": 1,
              "maxItems": 5,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "inspection",
                  "appraisal",
                  "loan",
                  "hoa",
                  "sale-of-home"
                ]
              }
            },
            "kind": {
              "type": "string",
              "const": "contingency_removal"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "draftId": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "kind": {
              "type": "string",
              "const": "counter_response"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "documentIds": {
              "minItems": 1,
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,200}$"
              }
            },
            "kind": {
              "type": "string",
              "const": "document_signing"
            },
            "packageId": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "draftId": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "kind": {
              "type": "string",
              "const": "repair_request"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "draftId": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            },
            "kind": {
              "type": "string",
              "const": "verification"
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        }
      ]
    },
    "workspaceId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    }
  },
  "required": [
    "ceremony",
    "workspaceId"
  ],
  "additionalProperties": false
}

Full output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ceremonyUrl": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2048,
          "format": "uri"
        },
        {
          "type": "null"
        }
      ]
    },
    "eligibility": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "enum": [
            "ELIGIBLE",
            "ALREADY_IN_PROGRESS",
            "ALREADY_RATIFIED",
            "CONTINGENCY_DEADLINE_UNRESOLVED",
            "CONTINGENCY_REMOVED",
            "CONTINGENCY_WAIVED",
            "MISSING_CONTRACT_DATE",
            "NOT_OPEN_CONTRACT",
            "RATIFICATION_NOT_PENDING",
            "TERMINAL_TRANSACTION"
          ]
        },
        "state": {
          "type": "string",
          "enum": [
            "eligible",
            "eligible_after_confirmation",
            "already_in_progress",
            "rights_uncertain",
            "unavailable"
          ]
        }
      },
      "required": [
        "reason",
        "state"
      ],
      "additionalProperties": false
    },
    "kind": {
      "type": "string",
      "enum": [
        "addendum",
        "buyer_visual_inspection",
        "cancellation",
        "contingency_removal",
        "counter_response",
        "document_signing",
        "repair_request",
        "verification"
      ]
    },
    "next": {
      "type": "string",
      "enum": [
        "not_available",
        "open_ceremony",
        "confirm_agreement",
        "awaiting_co_buyer",
        "deliver_signed_document",
        "complete"
      ]
    },
    "reasons": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 300
      }
    },
    "schemaVersion": {
      "type": "string",
      "const": "1"
    },
    "signedDocumentIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,200}$"
      }
    },
    "tasks": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "actionLabel": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "documentIds": {
            "maxItems": 20,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,200}$"
            }
          },
          "id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,200}$"
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 400
              }
            ]
          },
          "packageId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,200}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "needs_action",
              "waiting",
              "completed"
            ]
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "actionLabel",
          "documentIds",
          "id",
          "packageId",
          "status",
          "title",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    },
    "workspaceId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    }
  },
  "required": [
    "ceremonyUrl",
    "eligibility",
    "kind",
    "next",
    "reasons",
    "schemaVersion",
    "signedDocumentIds",
    "tasks",
    "workspaceId"
  ],
  "additionalProperties": false
}

Tool annotations

{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": true
}

Reference 00e5441a095c7e20. Download the full catalog.