← Tool reference

record_disclosure_findings

Record disclosure findings

Use this after reading disclosure pages with get_disclosure_pages to record your own review, one batch at a time: findings, and the documents you finished (reviewedDocuments by ref, including ones with nothing worth noting). Each finding's evidence is one to five quotes written as a page ref, a colon, and words copied exactly from that page ("D3.p12: Seller is aware of a roof leak"). Ohvii checks every quote against its page and refuses a finding it cannot verify, boilerplate, or a claim that something is missing, each with a reason to fix and resend; accepted findings appear in the buyer's review room as your reading. Write property-specific, evidence-first findings: review_first for concrete conditions, obligations, contradictions and deadlines; follow_up for what needs a question, a missing record or a professional; reference for neutral or positive context. Up to 25 findings a call; reuse a key to replace a finding (only the last occurrence of a key in a batch is evaluated). A rejected batch blocks completion until its mutationId is resolved through resolveRejectedBatchIds after correcting or deliberately excluding every rejected item; failed corrections do not resolve it. Send complete true once every document is covered and analysis.unresolvedRejectedBatchIds is empty, then walk the buyer through the result from get_disclosure_package. Use a new mutationId for each batch and reuse one only to retry that same batch. It signs nothing and sends nothing.

Effect
Draft or workspace edit
Required scopes
workspace:write
Workflow stages
offer, transaction
Data classes
disclosures, documents
Operation cost
2 weighted units; additional domain limits may apply.
Configurations
Standard, Buyer UI v2
Muse proposal
Write. Creates or updates draft, document, or workspace data within the authorized workflow. 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.

FieldRequiredMeaning and constraints
completebooleanNo

True once every document is covered and every rejected batch has been resolved; closes this AI's analysis, separate from the buyer's review.

findingsarray<object>No

New or corrected findings from the pages you read (up to 25 a call). A document with nothing worth noting needs none.

Maximum items: 25.

findings: nested contract
Array item contract

Extra fields are not allowed.

FieldRequiredMeaning and constraints
categorystringYes

Allowed: "structure", "roof", "plumbing", "electrical", "heating_cooling", "drainage_grading", "pest", "environmental", "sewer_septic", "water_supply", "pool_spa", "chimney_fireplace", "permits_legal", "title", "hoa", "insurance", "appliances_systems", "positive_information", "other".

confidencenumberNo

How sure the pages make you, 0 to 1. Omit for the tier's default.

Minimum: 0.

Maximum: 1.

evidencearray<string>Yes

One to five quotes, each a page ref from get_disclosure_pages, a colon, then up to 800 characters copied exactly from that page, for example "D3.p12: Seller is aware of a roof leak in the family room".

Minimum items: 1.

Maximum items: 5.

evidence: nested contract
Array item contract

Minimum characters: 6. Maximum characters: 840.

implicationstringNo

Why it matters to this buyer, written conditionally; empty when the page does not support one.

Maximum characters: 1500.

keystringNo

Your own short label for this finding; a later finding with the same key replaces it. Within one batch only the last occurrence of a key is evaluated.

Minimum characters: 1.

Maximum characters: 80.

observationstringYes

What the document says about this property, in plain words.

Minimum characters: 1.

Maximum characters: 1500.

suggestedQuestionstringNo

A question for the seller, listing agent, or a professional.

Maximum characters: 1500.

tierstringYes

review_first: concrete conditions, obligations, contradictions or deadlines to read early; follow_up: needs a question, a missing record or a professional; reference: neutral or positive context.

Allowed: "review_first", "follow_up", "reference".

mutationIdstringYes

A fresh random UUID (v4) you generate for this mutation. Send the same UUID only to retry the identical mutation; never a readable label.

Format: uuid.

Pattern validation applies; see the raw schema.

packageIdstringYes

Pattern validation applies; see the raw schema.

replaceFindingIdsarray<string>No

Ids of findings you recorded earlier on this version that these supersede; they are removed.

Maximum items: 50.

replaceFindingIds: nested contract
Array item contract

Pattern validation applies; see the raw schema.

resolveRejectedBatchIdsarray<string>No

Earlier rejected mutationIds you have corrected with this batch or deliberately excluded as unsupported or irrelevant. Resolve every rejected item in each named batch. New rejections leave those IDs unresolved; an empty batch may explicitly discard them.

Maximum items: 100.

resolveRejectedBatchIds: nested contract
Array item contract

Format: uuid. Pattern validation applies; see the raw schema.

reviewedDocumentsarray<string>No

Documents you finished reading in full, by ref (D1, D2, ...) or id, including ones with nothing worth noting.

Maximum items: 100.

reviewedDocuments: nested contract
Array item contract

Minimum characters: 1. Maximum characters: 200.

versionIdstringYes

Pattern validation applies; see the raw schema.

workspaceIdstringYes

Pattern validation applies; see the raw schema.

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

FieldRequiredMeaning and constraints
acceptedarray<object>Yes

Maximum items: 25.

accepted: nested contract
Array item contract

Extra fields are not allowed.

FieldRequiredMeaning and constraints
findingIdstringYes

Pattern validation applies; see the raw schema.

indexintegerYes

Minimum: 0.

Maximum: 9007199254740991.

keystring | nullYes

Must match at least one alternative.

key: nested contract
Alternative 1: string

Maximum characters: 80.

Alternative 2: null

tierstringYes

Allowed: "review_first", "follow_up", "reference".

analysisobjectYes

Extra fields are not allowed.

analysis: nested contract
FieldRequiredMeaning and constraints
completedAtstring | nullYes

Must match at least one alternative.

completedAt: nested contract
Alternative 1: string

Format: date-time. Pattern validation applies; see the raw schema.

Alternative 2: null

documentsReviewedintegerYes

Minimum: 0.

Maximum: 9007199254740991.

documentsTotalintegerYes

Minimum: 0.

Maximum: 9007199254740991.

findingCountsobjectYes

Extra fields are not allowed.

findingCounts: nested contract
FieldRequiredMeaning and constraints
follow_upintegerYes

Minimum: 0.

Maximum: 9007199254740991.

referenceintegerYes

Minimum: 0.

Maximum: 9007199254740991.

review_firstintegerYes

Minimum: 0.

Maximum: 9007199254740991.

statusstringYes

Allowed: "complete", "disabled", "partial", "unavailable", "awaiting_buyer_ai".

unresolvedRejectedBatchIdsarray<string>Yes

Maximum items: 100.

unresolvedRejectedBatchIds: nested contract
Array item contract

Format: uuid. Pattern validation applies; see the raw schema.

mutationIdstringYes

A fresh random UUID (v4) you generate for this mutation. Send the same UUID only to retry the identical mutation; never a readable label.

Format: uuid.

Pattern validation applies; see the raw schema.

nextstringYes

Allowed: "resolve_findings", "read_more", "complete_review", "summarize_for_buyer".

packageIdstringYes

Pattern validation applies; see the raw schema.

rejectedarray<object>Yes

Maximum items: 25.

rejected: nested contract
Array item contract

Extra fields are not allowed.

FieldRequiredMeaning and constraints
evidencearray<object>Yes

Maximum items: 5.

evidence: nested contract
Array item contract

Extra fields are not allowed.

FieldRequiredMeaning and constraints
foundbooleanYesNo additional description in the contract.
refstringYes

Maximum characters: 20.

indexintegerYes

Minimum: 0.

Maximum: 9007199254740991.

keystring | nullYes

Must match at least one alternative.

key: nested contract
Alternative 1: string

Maximum characters: 80.

Alternative 2: null

messagestringYes

Maximum characters: 600.

reasonstringYes

Allowed: "absence_inference", "boilerplate", "citation_not_found", "invalid_evidence", "limit_reached".

remainingDocumentsarray<object>Yes

Maximum items: 10.

remainingDocuments: nested contract
Array item contract

Extra fields are not allowed.

FieldRequiredMeaning and constraints
idstringYes

Pattern validation applies; see the raw schema.

kindstringYes

Minimum characters: 1.

Maximum characters: 80.

labelstring | nullYes

Must match at least one alternative.

label: nested contract
Alternative 1: string

Maximum characters: 6000.

Alternative 2: null

pageCountintegerYes

Minimum: 0.

Maximum: 9007199254740991.

refstringYes

Maximum characters: 10.

removedFindingIdsarray<string>Yes

Maximum items: 200.

removedFindingIds: nested contract
Array item contract

Pattern validation applies; see the raw schema.

replayedbooleanYesNo additional description in the contract.
schemaVersionstringYes

Must be "1".

versionIdstringYes

Pattern validation applies; see the raw schema.

workspaceIdstringYes

Pattern validation applies; see the raw schema.

Raw input schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "complete": {
      "description": "True once every document is covered and every rejected batch has been resolved; closes this AI's analysis, separate from the buyer's review.",
      "type": "boolean"
    },
    "findings": {
      "description": "New or corrected findings from the pages you read (up to 25 a call). A document with nothing worth noting needs none.",
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "structure",
              "roof",
              "plumbing",
              "electrical",
              "heating_cooling",
              "drainage_grading",
              "pest",
              "environmental",
              "sewer_septic",
              "water_supply",
              "pool_spa",
              "chimney_fireplace",
              "permits_legal",
              "title",
              "hoa",
              "insurance",
              "appliances_systems",
              "positive_information",
              "other"
            ]
          },
          "confidence": {
            "description": "How sure the pages make you, 0 to 1. Omit for the tier's default.",
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "evidence": {
            "minItems": 1,
            "maxItems": 5,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 6,
              "maxLength": 840
            },
            "description": "One to five quotes, each a page ref from get_disclosure_pages, a colon, then up to 800 characters copied exactly from that page, for example \"D3.p12: Seller is aware of a roof leak in the family room\"."
          },
          "implication": {
            "description": "Why it matters to this buyer, written conditionally; empty when the page does not support one.",
            "type": "string",
            "maxLength": 1500
          },
          "key": {
            "description": "Your own short label for this finding; a later finding with the same key replaces it. Within one batch only the last occurrence of a key is evaluated.",
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "observation": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1500,
            "description": "What the document says about this property, in plain words."
          },
          "suggestedQuestion": {
            "description": "A question for the seller, listing agent, or a professional.",
            "type": "string",
            "maxLength": 1500
          },
          "tier": {
            "type": "string",
            "enum": [
              "review_first",
              "follow_up",
              "reference"
            ],
            "description": "review_first: concrete conditions, obligations, contradictions or deadlines to read early; follow_up: needs a question, a missing record or a professional; reference: neutral or positive context."
          }
        },
        "required": [
          "category",
          "evidence",
          "observation",
          "tier"
        ],
        "additionalProperties": false
      }
    },
    "mutationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "A fresh random UUID (v4) you generate for this mutation. Send the same UUID only to retry the identical mutation; never a readable label."
    },
    "packageId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    },
    "replaceFindingIds": {
      "description": "Ids of findings you recorded earlier on this version that these supersede; they are removed.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,200}$"
      }
    },
    "resolveRejectedBatchIds": {
      "description": "Earlier rejected mutationIds you have corrected with this batch or deliberately excluded as unsupported or irrelevant. Resolve every rejected item in each named batch. New rejections leave those IDs unresolved; an empty batch may explicitly discard them.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "reviewedDocuments": {
      "description": "Documents you finished reading in full, by ref (D1, D2, ...) or id, including ones with nothing worth noting.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    },
    "workspaceId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    }
  },
  "required": [
    "mutationId",
    "packageId",
    "versionId",
    "workspaceId"
  ],
  "additionalProperties": false
}
Full output schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accepted": {
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "findingId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,200}$"
          },
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "key": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 80
              },
              {
                "type": "null"
              }
            ]
          },
          "tier": {
            "type": "string",
            "enum": [
              "review_first",
              "follow_up",
              "reference"
            ]
          }
        },
        "required": [
          "findingId",
          "index",
          "key",
          "tier"
        ],
        "additionalProperties": false
      }
    },
    "analysis": {
      "type": "object",
      "properties": {
        "completedAt": {
          "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"
            }
          ]
        },
        "documentsReviewed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "documentsTotal": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "findingCounts": {
          "type": "object",
          "properties": {
            "follow_up": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "reference": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "review_first": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "follow_up",
            "reference",
            "review_first"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "complete",
            "disabled",
            "partial",
            "unavailable",
            "awaiting_buyer_ai"
          ]
        },
        "unresolvedRejectedBatchIds": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        }
      },
      "required": [
        "completedAt",
        "documentsReviewed",
        "documentsTotal",
        "findingCounts",
        "status",
        "unresolvedRejectedBatchIds"
      ],
      "additionalProperties": false
    },
    "mutationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "A fresh random UUID (v4) you generate for this mutation. Send the same UUID only to retry the identical mutation; never a readable label."
    },
    "next": {
      "type": "string",
      "enum": [
        "resolve_findings",
        "read_more",
        "complete_review",
        "summarize_for_buyer"
      ]
    },
    "packageId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    },
    "rejected": {
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "evidence": {
            "maxItems": 5,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "found": {
                  "type": "boolean"
                },
                "ref": {
                  "type": "string",
                  "maxLength": 20
                }
              },
              "required": [
                "found",
                "ref"
              ],
              "additionalProperties": false
            }
          },
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "key": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 80
              },
              {
                "type": "null"
              }
            ]
          },
          "message": {
            "type": "string",
            "maxLength": 600
          },
          "reason": {
            "type": "string",
            "enum": [
              "absence_inference",
              "boilerplate",
              "citation_not_found",
              "invalid_evidence",
              "limit_reached"
            ]
          }
        },
        "required": [
          "evidence",
          "index",
          "key",
          "message",
          "reason"
        ],
        "additionalProperties": false
      }
    },
    "remainingDocuments": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,200}$"
          },
          "kind": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "label": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 6000
              },
              {
                "type": "null"
              }
            ]
          },
          "pageCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "ref": {
            "type": "string",
            "maxLength": 10
          }
        },
        "required": [
          "id",
          "kind",
          "label",
          "pageCount",
          "ref"
        ],
        "additionalProperties": false
      }
    },
    "removedFindingIds": {
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,200}$"
      }
    },
    "replayed": {
      "type": "boolean"
    },
    "schemaVersion": {
      "type": "string",
      "const": "1"
    },
    "versionId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    },
    "workspaceId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,200}$"
    }
  },
  "required": [
    "accepted",
    "analysis",
    "mutationId",
    "next",
    "packageId",
    "rejected",
    "remainingDocuments",
    "removedFindingIds",
    "replayed",
    "schemaVersion",
    "versionId",
    "workspaceId"
  ],
  "additionalProperties": false
}
Tool annotations
{
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": false,
  "readOnlyHint": false
}

Reference 00e5441a095c7e20. Download the full catalog.