{ "openapi": "3.1.0", "info": { "title": "Casa Agent API", "version": "1.0.0", "summary": "Read and update a Casa home record from an agent running outside Casa.", "description": "Every call carries `Authorization: Bearer `. A key is made by a signed-in person at https://dear.casa/settings/external-agent, acts as that one account, and is narrowed by the scopes chosen when it was made. Permission is then checked per home exactly as for the in-app assistant; a refused call is HTTP 200 with `ok: false` and must not be retried. Human guide: https://dear.casa/docs/agent-api — Markdown: https://dear.casa/docs/agent-api.md" }, "servers": [ { "url": "https://dear.casa" } ], "security": [ { "casaKey": [] } ], "tags": [ { "name": "tools", "description": "The catalog, and running one tool." }, { "name": "mind", "description": "The Casa Agent's memory: read it, or propose to it." } ], "paths": { "/api/agent/external/tools": { "get": { "tags": [ "tools" ], "operationId": "getCatalog", "summary": "List every tool, with the scope each needs and whether this key holds it.", "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "401": { "description": "No key, a wrong key, or a key that has been turned off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the needed scope (see `requiredScope`), or the assistant is switched off for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "tools" ], "operationId": "runTool", "summary": "Run one tool.", "description": "The body is one of the `*Call` schemas, chosen by `tool`. The key must hold the tool’s scope, plus `files:write` if `attachments` is non-empty. Permission on the module in the named home is checked next; a refusal answers 200 with `ok: false`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SearchInventoryCall" }, { "$ref": "#/components/schemas/ListContactsCall" }, { "$ref": "#/components/schemas/ListNotesCall" }, { "$ref": "#/components/schemas/ListRecentActivityCall" }, { "$ref": "#/components/schemas/ListExpensesCall" }, { "$ref": "#/components/schemas/ListServicesCall" }, { "$ref": "#/components/schemas/GetMortgageCall" }, { "$ref": "#/components/schemas/ListTasksCall" }, { "$ref": "#/components/schemas/ListCalendarEventsCall" }, { "$ref": "#/components/schemas/ListFloorsCall" }, { "$ref": "#/components/schemas/ListFoldersCall" }, { "$ref": "#/components/schemas/ListWarrantiesCall" }, { "$ref": "#/components/schemas/ListInsuranceCall" }, { "$ref": "#/components/schemas/ListMaintenanceCall" }, { "$ref": "#/components/schemas/ListIrrigationZonesCall" }, { "$ref": "#/components/schemas/ListIrrigationRunsCall" }, { "$ref": "#/components/schemas/FindFilesCall" }, { "$ref": "#/components/schemas/ReadDocumentCall" }, { "$ref": "#/components/schemas/LogActivityCall" }, { "$ref": "#/components/schemas/CreateInventoryItemCall" }, { "$ref": "#/components/schemas/UpdateInventoryItemCall" }, { "$ref": "#/components/schemas/CreateServiceCall" }, { "$ref": "#/components/schemas/UpdateServiceCall" }, { "$ref": "#/components/schemas/CreateContactCall" }, { "$ref": "#/components/schemas/UpdateContactCall" }, { "$ref": "#/components/schemas/CreateNoteCall" }, { "$ref": "#/components/schemas/UpdateNoteCall" }, { "$ref": "#/components/schemas/CreateExpenseCall" }, { "$ref": "#/components/schemas/UpdateExpenseCall" }, { "$ref": "#/components/schemas/CreateMortgageCall" }, { "$ref": "#/components/schemas/UpdateMortgageCall" }, { "$ref": "#/components/schemas/CreateWarrantyCall" }, { "$ref": "#/components/schemas/UpdateWarrantyCall" }, { "$ref": "#/components/schemas/CreateTaskCall" }, { "$ref": "#/components/schemas/UpdateTaskCall" }, { "$ref": "#/components/schemas/CreateCalendarEventCall" }, { "$ref": "#/components/schemas/UpdateCalendarEventCall" }, { "$ref": "#/components/schemas/CreateFloorCall" }, { "$ref": "#/components/schemas/UpdateFloorCall" }, { "$ref": "#/components/schemas/CreateRoomCall" }, { "$ref": "#/components/schemas/UpdateRoomCall" }, { "$ref": "#/components/schemas/CompleteMaintenanceCall" }, { "$ref": "#/components/schemas/CreateMaintenancePlanCall" }, { "$ref": "#/components/schemas/UpdateMaintenancePlanCall" }, { "$ref": "#/components/schemas/CreateInsurancePolicyCall" }, { "$ref": "#/components/schemas/UpdateInsurancePolicyCall" }, { "$ref": "#/components/schemas/RunIrrigationZoneCall" }, { "$ref": "#/components/schemas/StopIrrigationZoneCall" }, { "$ref": "#/components/schemas/AttachFileCall" }, { "$ref": "#/components/schemas/UploadToFilesCall" }, { "$ref": "#/components/schemas/CreateFolderCall" }, { "$ref": "#/components/schemas/UpdateFolderCall" }, { "$ref": "#/components/schemas/ReadMemoryCall" } ], "discriminator": { "propertyName": "tool", "mapping": { "search_inventory": "#/components/schemas/SearchInventoryCall", "list_contacts": "#/components/schemas/ListContactsCall", "list_notes": "#/components/schemas/ListNotesCall", "list_recent_activity": "#/components/schemas/ListRecentActivityCall", "list_expenses": "#/components/schemas/ListExpensesCall", "list_services": "#/components/schemas/ListServicesCall", "get_mortgage": "#/components/schemas/GetMortgageCall", "list_tasks": "#/components/schemas/ListTasksCall", "list_calendar_events": "#/components/schemas/ListCalendarEventsCall", "list_floors": "#/components/schemas/ListFloorsCall", "list_folders": "#/components/schemas/ListFoldersCall", "list_warranties": "#/components/schemas/ListWarrantiesCall", "list_insurance": "#/components/schemas/ListInsuranceCall", "list_maintenance": "#/components/schemas/ListMaintenanceCall", "list_irrigation_zones": "#/components/schemas/ListIrrigationZonesCall", "list_irrigation_runs": "#/components/schemas/ListIrrigationRunsCall", "find_files": "#/components/schemas/FindFilesCall", "read_document": "#/components/schemas/ReadDocumentCall", "log_activity": "#/components/schemas/LogActivityCall", "create_inventory_item": "#/components/schemas/CreateInventoryItemCall", "update_inventory_item": "#/components/schemas/UpdateInventoryItemCall", "create_service": "#/components/schemas/CreateServiceCall", "update_service": "#/components/schemas/UpdateServiceCall", "create_contact": "#/components/schemas/CreateContactCall", "update_contact": "#/components/schemas/UpdateContactCall", "create_note": "#/components/schemas/CreateNoteCall", "update_note": "#/components/schemas/UpdateNoteCall", "create_expense": "#/components/schemas/CreateExpenseCall", "update_expense": "#/components/schemas/UpdateExpenseCall", "create_mortgage": "#/components/schemas/CreateMortgageCall", "update_mortgage": "#/components/schemas/UpdateMortgageCall", "create_warranty": "#/components/schemas/CreateWarrantyCall", "update_warranty": "#/components/schemas/UpdateWarrantyCall", "create_task": "#/components/schemas/CreateTaskCall", "update_task": "#/components/schemas/UpdateTaskCall", "create_calendar_event": "#/components/schemas/CreateCalendarEventCall", "update_calendar_event": "#/components/schemas/UpdateCalendarEventCall", "create_floor": "#/components/schemas/CreateFloorCall", "update_floor": "#/components/schemas/UpdateFloorCall", "create_room": "#/components/schemas/CreateRoomCall", "update_room": "#/components/schemas/UpdateRoomCall", "complete_maintenance": "#/components/schemas/CompleteMaintenanceCall", "create_maintenance_plan": "#/components/schemas/CreateMaintenancePlanCall", "update_maintenance_plan": "#/components/schemas/UpdateMaintenancePlanCall", "create_insurance_policy": "#/components/schemas/CreateInsurancePolicyCall", "update_insurance_policy": "#/components/schemas/UpdateInsurancePolicyCall", "run_irrigation_zone": "#/components/schemas/RunIrrigationZoneCall", "stop_irrigation_zone": "#/components/schemas/StopIrrigationZoneCall", "attach_file": "#/components/schemas/AttachFileCall", "upload_to_files": "#/components/schemas/UploadToFilesCall", "create_folder": "#/components/schemas/CreateFolderCall", "update_folder": "#/components/schemas/UpdateFolderCall", "read_memory": "#/components/schemas/ReadMemoryCall" } } } } } }, "responses": { "200": { "description": "The call was answered. Check `ok`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolResult" } } } }, "400": { "description": "The body was not JSON, or a field had the wrong shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, a wrong key, or a key that has been turned off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the needed scope (see `requiredScope`), or the assistant is switched off for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No tool by that name is reachable from outside Casa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/external/mind": { "get": { "tags": [ "mind" ], "operationId": "getMindIndex", "summary": "The Agent's rendered, redacted memory index.", "description": "Needs `mind:read`. Read-only: there is no POST here.", "responses": { "200": { "description": "The index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MindIndex" } } } }, "401": { "description": "No key, a wrong key, or a key that has been turned off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the needed scope (see `requiredScope`), or the assistant is switched off for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/external/mind/suggest": { "post": { "tags": [ "mind" ], "operationId": "suggestMemory", "summary": "Propose something for the Casa Agent to remember.", "description": "Needs `mind:suggest`. The Agent decides; `recorded: false` is a normal answer. Limited to 10 per minute per account, one at a time, because it spends the account's AI budget.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suggestion" } } } }, "responses": { "200": { "description": "Considered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionResult" } } } }, "400": { "description": "`suggestion` missing, empty, or too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, a wrong key, or a key that has been turned off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the needed scope (see `requiredScope`), or the assistant is switched off for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many calls. `Retry-After` says how long to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "casaKey": { "type": "http", "scheme": "bearer", "description": "A key made at https://dear.casa/settings/external-agent. Shown once; Casa keeps only a hash. Turning it off takes effect on the next call." } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "string", "description": "Why, in plain language." }, "requiredScope": { "type": "string", "description": "On a 403 for a missing scope: the scope to re-mint with." } } }, "Attachment": { "type": "object", "required": [ "filename", "mimeType", "data" ], "properties": { "filename": { "type": "string" }, "mimeType": { "type": "string", "description": "The file’s media type, e.g. application/pdf." }, "data": { "type": "string", "contentEncoding": "base64", "description": "The bytes, base64. At most 10 MB decoded." } } }, "ToolResult": { "type": "object", "required": [ "ok", "result", "tool" ], "properties": { "ok": { "type": "boolean", "description": "False when the call was refused or failed. A refusal is an answer, not an error: do not retry it." }, "tool": { "type": "string" }, "result": { "type": "string", "description": "A sentence in plain language with real values, written to be relayed to a person." }, "created": { "type": "object", "description": "Present when the tool made something.", "required": [ "entityType", "id", "homeId", "name" ], "properties": { "entityType": { "type": "string" }, "id": { "type": "string" }, "homeId": { "type": "string" }, "name": { "type": "string" } } }, "correlationId": { "type": "string" } } }, "CatalogTool": { "type": "object", "required": [ "name", "description", "parameters", "scope", "kind", "allowed" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema for `args`." }, "scope": { "type": "string", "enum": [ "record:read", "record:write", "files:write", "mind:read", "mind:suggest" ] }, "kind": { "type": "string", "enum": [ "read", "document", "action", "mind" ] }, "module": { "type": [ "string", "null" ] }, "capability": { "type": [ "string", "null" ] }, "confirm": { "type": [ "string", "null" ], "enum": [ "auto", "always", null ] }, "allowed": { "type": "boolean", "description": "Whether the calling key holds `scope`." } } }, "Catalog": { "type": "object", "required": [ "ok", "scopes", "attachments", "tools" ], "properties": { "ok": { "const": true }, "scopes": { "type": "object", "properties": { "held": { "type": "array", "items": { "type": "string", "enum": [ "record:read", "record:write", "files:write", "mind:read", "mind:suggest" ] } }, "all": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "grants": { "type": "string" } } } } } }, "attachments": { "type": "object", "properties": { "maxPerCall": { "type": "integer" }, "maxBytes": { "type": "integer" } } }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogTool" } } } }, "MindIndex": { "type": "object", "required": [ "ok", "index", "nodeCount", "linkCount" ], "properties": { "ok": { "const": true }, "index": { "type": "string", "description": "The rendered, redacted index — the same text the Casa Agent reads." }, "nodeCount": { "type": "integer" }, "linkCount": { "type": "integer" }, "readPage": { "type": "object", "description": "How to read one page in full (`read_memory`)." } } }, "Suggestion": { "type": "object", "required": [ "suggestion" ], "properties": { "suggestion": { "type": "string", "maxLength": 2000 }, "source": { "type": "string", "maxLength": 60, "description": "Who is proposing, e.g. the agent’s name." }, "correlationId": { "type": "string", "maxLength": 200 } } }, "SuggestionResult": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "recorded": { "type": "boolean", "description": "False is a normal answer: the Casa Agent read it and chose not to keep it." }, "note": { "type": "string" }, "reason": { "type": "string", "description": "When `ok` is false: why no model was available." }, "calls": { "type": "array", "items": { "type": "string" }, "description": "Names of the memory tools the Agent used." }, "correlationId": { "type": "string" } } }, "SearchInventoryCall": { "type": "object", "required": [ "tool" ], "description": "Search a home's inventory items (appliances, fixtures, electronics). Filter by a free-text query (name/make/model) and/or category. Returns each item's id (needed to update it or link it elsewhere), make, model, serial number, purchase info.", "properties": { "tool": { "const": "search_inventory" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "query": { "type": "string", "description": "Free-text match on name, make, or model." }, "category": { "type": "string", "description": "Exact category to filter by." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "home.inventory", "x-casa-capability": "view", "x-casa-confirm": null }, "ListContactsCall": { "type": "object", "required": [ "tool" ], "description": "List a home's contacts / vendors (people and companies — plumbers, electricians, providers). Returns each contact's id (needed to update it or link it to a service/expense), name, company, category, and rating. Optional free-text query on name/company.", "properties": { "tool": { "const": "list_contacts" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "query": { "type": "string", "description": "Free-text match on name or company." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "contacts", "x-casa-capability": "view", "x-casa-confirm": null }, "ListNotesCall": { "type": "object", "required": [ "tool" ], "description": "List a home's notes (free-form sticky notes about the home or an item). Returns each note's id (needed to update it), title, and a snippet. Newest first.", "properties": { "tool": { "const": "list_notes" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "limit": { "type": "number", "description": "How many (max 30)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.notes", "x-casa-capability": "view", "x-casa-confirm": null }, "ListRecentActivityCall": { "type": "object", "required": [ "tool" ], "description": "List a home's most recent activity/timeline events, each with its id. Optional limit (default 15). Use the id with attach_file (target_type 'timeline') to file a photo onto something already logged.", "properties": { "tool": { "const": "list_recent_activity" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "limit": { "type": "number", "description": "How many (max 40)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "activity.timeline", "x-casa-capability": "view", "x-casa-confirm": null }, "ListExpensesCall": { "type": "object", "required": [ "tool" ], "description": "Summarize a home's expenses for a year (default current): total, breakdown by category, and the largest entries.", "properties": { "tool": { "const": "list_expenses" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "year": { "type": "number", "description": "Calendar year, e.g. 2026." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.expenses", "x-casa-capability": "view", "x-casa-confirm": null }, "ListServicesCall": { "type": "object", "required": [ "tool" ], "description": "List a home's active services (utilities, internet, recurring services, coverage) with each service's id (needed to update it), cost and provider.", "properties": { "tool": { "const": "list_services" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.services", "x-casa-capability": "view", "x-casa-confirm": null }, "GetMortgageCall": { "type": "object", "required": [ "tool" ], "description": "Get a home's mortgage details: its id (needed to update it), lender, rate, term, original amount, value, balance.", "properties": { "tool": { "const": "get_mortgage" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.mortgage", "x-casa-capability": "view", "x-casa-confirm": null }, "ListTasksCall": { "type": "object", "required": [ "tool" ], "description": "List a home's to-do tasks with each task's id (needed to update or complete it), title, status, priority, and due date. Defaults to open tasks.", "properties": { "tool": { "const": "list_tasks" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "status": { "type": "string", "description": "Filter: 'open' (default), 'done', 'snoozed', 'dismissed', or 'all'." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "activity.tasks", "x-casa-capability": "view", "x-casa-confirm": null }, "ListCalendarEventsCall": { "type": "object", "required": [ "tool" ], "description": "List a home's upcoming calendar events with each event's id (needed to update or cancel it), title, start date, and type. Newest-upcoming first.", "properties": { "tool": { "const": "list_calendar_events" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "limit": { "type": "number", "description": "How many (max 40)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "activity.calendar", "x-casa-capability": "view", "x-casa-confirm": null }, "ListFloorsCall": { "type": "object", "required": [ "tool" ], "description": "List a home's floors and the rooms on each, with ids. Use this to get a floor id (to edit a floor) or a room id (to edit a room, or to link a task/event/item to a room).", "properties": { "tool": { "const": "list_floors" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "home.profile", "x-casa-capability": "view", "x-casa-confirm": null }, "ListFoldersCall": { "type": "object", "required": [ "tool" ], "description": "List the folders in a home's Files: each folder's id (needed to rename it or nest a new folder under it), its full path, and how many documents it holds DIRECTLY that this user may see — a subfolder's contents are counted on the subfolder's own line, not the parent's. It returns no file names: to say what is actually filed anywhere, call find_files. This list is not evidence about what does or does not exist — folders this user is not allowed to see are not listed at all, so never conclude from it that a folder or a document is missing. If a folder you expected is absent, say you cannot see it rather than that it does not exist, and never offer to create one without checking with find_files first.", "properties": { "tool": { "const": "list_folders" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.files", "x-casa-capability": "view", "x-casa-confirm": null }, "ListWarrantiesCall": { "type": "object", "required": [ "tool" ], "description": "List a home's warranties with each warranty's id (needed to update it or attach its certificate/receipt), the item it covers, type, provider, expiry date, and status (active/expiring/expired).", "properties": { "tool": { "const": "list_warranties" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.warranty", "x-casa-capability": "view", "x-casa-confirm": null }, "ListInsuranceCall": { "type": "object", "required": [ "tool" ], "description": "List a home's insurance policies with each policy's id (needed to attach its declarations page / policy document / ID cards), type (home/auto/life/etc.), insurer, policy number, what it insures, expiry date, and status (active/expiring/expired).", "properties": { "tool": { "const": "list_insurance" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.insurance", "x-casa-capability": "view", "x-casa-confirm": null }, "ListMaintenanceCall": { "type": "object", "required": [ "tool" ], "description": "List a home's recurring maintenance plans with each plan's id (needed to mark one done with complete_maintenance), how often it runs, when it was last done, when it is next due, its status (overdue/due/scheduled/paused), what it is attached to, and the other names people call it. Use it to answer \"what's due?\", \"when did I last do the gutters?\", or to find the plan a user's description matches before proposing complete_maintenance. NO MONEY: this tool never reports what a plan has cost — use list_expenses for spend.", "properties": { "tool": { "const": "list_maintenance" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "filter": { "type": "string", "description": "Narrow the list: 'overdue', 'due' (overdue or due now), 'active' (default — everything running), or 'all' (includes paused plans)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.maintenance", "x-casa-capability": "view", "x-casa-confirm": null }, "ListIrrigationZonesCall": { "type": "object", "required": [ "tool" ], "description": "List a home's irrigation controllers and their watering zones, with each zone's id (needed to run or stop it), its number, the areas it waters, whether it is enabled, and when it last ran. Use it for \"which zones do I have?\", \"when did the back lawn last run?\", or to find the zone a user's description matches before proposing run_irrigation_zone. NOT SETUP: this never reports the controller connection — adding a controller, its API key, and syncing are done in the app, not here.", "properties": { "tool": { "const": "list_irrigation_zones" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.irrigation", "x-casa-capability": "view", "x-casa-confirm": null }, "ListIrrigationRunsCall": { "type": "object", "required": [ "tool" ], "description": "List a home's recent irrigation runs, newest first: which zone ran, on what day, for how long, and whether it completed or was skipped (and why — rain, freeze, wind, saturation). Optionally narrow to one zone. Use it for \"did the sprinklers run this week?\", \"how much did I water in July?\", or \"why did it skip yesterday?\".", "properties": { "tool": { "const": "list_irrigation_runs" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "zone_id": { "type": "string", "description": "Optional — only this zone. Its id comes from list_irrigation_zones." }, "limit": { "type": "number", "description": "How many (max 40)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.irrigation", "x-casa-capability": "view", "x-casa-confirm": null }, "FindFilesCall": { "type": "object", "required": [ "tool" ], "description": "Find a document or photo in a home's Files — a manual, a policy, a receipt, an inspection report, a warranty certificate. Matches on the file name and, optionally, the folder it sits in. Returns each file's id (needed to read it with read_document), its name, its folder, and when it was added. Use it whenever the user asks you to pull up, find, or look at a document — and use it before ever telling someone a document is not there, because this is the only tool that can answer that.", "properties": { "tool": { "const": "find_files" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit if the account has only one home." }, "query": { "type": "string", "description": "Free-text match on the file name." }, "folder": { "type": "string", "description": "Optional folder to look in — its name ('Mortgage'), its full path exactly as list_folders prints it ('Finance / Mortgage'), or its id. Everything nested under that folder is searched too. Only files the user is allowed to see are returned, so an empty result means 'nothing you can see', not 'nothing exists'." }, "limit": { "type": "number", "description": "How many (max 30)." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "read", "x-casa-module": "tools.files", "x-casa-capability": "view", "x-casa-confirm": null }, "ReadDocumentCall": { "type": "object", "required": [ "tool" ], "description": "Read a document that is already saved in the home's Files and answer a specific question from what it says — a policy's deductible or coverage limit, a manual's filter size, an inspection's findings, a warranty's expiry. Find the file first with find_files to get its id. Ask ONE clear question per call. Only works on PDFs and photos. If the answer is not in the document, you will be told so — say that rather than guessing.", "properties": { "tool": { "const": "read_document" }, "args": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The file's id, from find_files." }, "question": { "type": "string", "description": "The single question to answer from the document, e.g. \"What is the wind/hail deductible?\"." } }, "required": [ "file_id", "question" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:read", "x-casa-kind": "document", "x-casa-module": null, "x-casa-capability": null, "x-casa-confirm": null }, "LogActivityCall": { "type": "object", "required": [ "tool" ], "description": "Log an event to a home's Activity/Timeline — e.g. the user says they did maintenance (\"I changed the furnace filter\"), had a repair, or wants a note recorded. This is a WRITE: it is proposed for the user's approval, not done immediately, so don't say you've already logged it. Gather the home (and item, if relevant) first, then propose one entry.", "properties": { "tool": { "const": "log_activity" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "type": { "type": "string", "description": "Short kind of event: 'maintenance', 'repair', 'note', 'purchase', 'general'." }, "description": { "type": "string", "description": "What happened, in the user's own terms. e.g. \"Changed the furnace filter\"." }, "occurred_at": { "type": "string", "description": "When it happened (ISO date, e.g. 2026-08-08). Omit for today." }, "item_id": { "type": "string", "description": "Optional inventory item id this event relates to (from search_inventory)." } }, "required": [ "type", "description" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "activity.timeline", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "CreateInventoryItemCall": { "type": "object", "required": [ "tool" ], "description": "Add a new inventory item (an appliance, fixture, electronic, tool, or safety device) to a home. A WRITE — proposed for approval, so don't say it's already added. Search first to avoid duplicates.", "properties": { "tool": { "const": "create_inventory_item" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "What the item is called, e.g. \"Kitchen refrigerator\"." }, "category": { "type": "string", "description": "Device type, e.g. Appliance, Electronic, Fixture, Tool." }, "make": { "type": "string", "description": "Manufacturer / brand." }, "model": { "type": "string", "description": "Model name or number." }, "serial_number": { "type": "string", "description": "Serial number, if known." }, "is_smart": { "type": "boolean", "description": "Connected / app-controlled device?" }, "is_safety": { "type": "boolean", "description": "Life-safety device (smoke/CO detector, alarm, extinguisher)?" }, "purchase_date": { "type": "string", "description": "When bought (ISO date)." }, "purchase_price": { "type": "number", "description": "Purchase price in dollars." }, "store": { "type": "string", "description": "Where it was bought." }, "install_date": { "type": "string", "description": "When installed (ISO date)." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.inventory", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateInventoryItemCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing inventory item — fill in or correct its make/model/serial/purchase details. Get its id from search_inventory first. A WRITE — proposed for approval. Only pass the fields you're changing.", "properties": { "tool": { "const": "update_inventory_item" }, "args": { "type": "object", "properties": { "item_id": { "type": "string", "description": "The item id (from search_inventory)." }, "name": { "type": "string", "description": "New name, if renaming." }, "category": { "type": "string", "description": "Device type, e.g. Appliance, Electronic, Fixture, Tool." }, "make": { "type": "string", "description": "Manufacturer / brand." }, "model": { "type": "string", "description": "Model name or number." }, "serial_number": { "type": "string", "description": "Serial number, if known." }, "is_smart": { "type": "boolean", "description": "Connected / app-controlled device?" }, "is_safety": { "type": "boolean", "description": "Life-safety device (smoke/CO detector, alarm, extinguisher)?" }, "purchase_date": { "type": "string", "description": "When bought (ISO date)." }, "purchase_price": { "type": "number", "description": "Purchase price in dollars." }, "store": { "type": "string", "description": "Where it was bought." }, "install_date": { "type": "string", "description": "When installed (ISO date)." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "item_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.inventory", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateServiceCall": { "type": "object", "required": [ "tool" ], "description": "Add a recurring service or utility (electric, internet, insurance, streaming, lawn care) to a home. A WRITE — proposed for approval. List existing services first to avoid duplicates.", "properties": { "tool": { "const": "create_service" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "What the service is called, e.g. \"City Water\" or \"Comcast Internet\"." }, "category": { "type": "string", "description": "e.g. Utilities, Internet, Insurance, Streaming, Lawn." }, "provider_name": { "type": "string", "description": "Company / provider name." }, "cost": { "type": "number", "description": "Amount billed per period, in dollars." }, "billing_period": { "type": "string", "description": "'monthly', 'quarterly', 'yearly'." }, "status": { "type": "string", "description": "'active', 'paused', or 'cancelled'." }, "autopay": { "type": "boolean", "description": "Is it on autopay?" }, "website": { "type": "string", "description": "Provider website." }, "phone": { "type": "string", "description": "Provider phone." }, "account_number": { "type": "string", "description": "Your account number with the provider." }, "renewal_date": { "type": "string", "description": "Renewal date (ISO)." }, "next_bill_date": { "type": "string", "description": "Next bill date (ISO)." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.services", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateServiceCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing service — change its cost, status, provider, or billing dates. Get its id from list_services first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_service" }, "args": { "type": "object", "properties": { "service_id": { "type": "string", "description": "The service id (from list_services)." }, "name": { "type": "string", "description": "New name, if renaming." }, "category": { "type": "string", "description": "e.g. Utilities, Internet, Insurance, Streaming, Lawn." }, "provider_name": { "type": "string", "description": "Company / provider name." }, "cost": { "type": "number", "description": "Amount billed per period, in dollars." }, "billing_period": { "type": "string", "description": "'monthly', 'quarterly', 'yearly'." }, "status": { "type": "string", "description": "'active', 'paused', or 'cancelled'." }, "autopay": { "type": "boolean", "description": "Is it on autopay?" }, "website": { "type": "string", "description": "Provider website." }, "phone": { "type": "string", "description": "Provider phone." }, "account_number": { "type": "string", "description": "Your account number with the provider." }, "renewal_date": { "type": "string", "description": "Renewal date (ISO)." }, "next_bill_date": { "type": "string", "description": "Next bill date (ISO)." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "service_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.services", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateContactCall": { "type": "object", "required": [ "tool" ], "description": "Add a contact / vendor (a plumber, electrician, HOA, landscaper, service provider) to a home. A WRITE — proposed for approval. List contacts first to avoid duplicates.", "properties": { "tool": { "const": "create_contact" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "The contact or company name." }, "contact_type": { "type": "string", "description": "'person' or 'company'." }, "category": { "type": "string", "description": "e.g. Plumber, Electrician, HOA, Landscaper." }, "company": { "type": "string", "description": "Employer/company (for a person)." }, "phone": { "type": "string", "description": "Phone number." }, "email": { "type": "string", "description": "Email address." }, "website": { "type": "string", "description": "Website." }, "address": { "type": "string", "description": "Address." }, "rating": { "type": "number", "description": "Optional 1–5 rating." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "contacts", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateContactCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing contact / vendor — correct their phone, email, category, or rating. Get the id from list_contacts first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_contact" }, "args": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "The contact id (from list_contacts)." }, "name": { "type": "string", "description": "New name, if renaming." }, "contact_type": { "type": "string", "description": "'person' or 'company'." }, "category": { "type": "string", "description": "e.g. Plumber, Electrician, HOA, Landscaper." }, "company": { "type": "string", "description": "Employer/company (for a person)." }, "phone": { "type": "string", "description": "Phone number." }, "email": { "type": "string", "description": "Email address." }, "website": { "type": "string", "description": "Website." }, "address": { "type": "string", "description": "Address." }, "rating": { "type": "number", "description": "Optional 1–5 rating." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "contact_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "contacts", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateNoteCall": { "type": "object", "required": [ "tool" ], "description": "Jot a free-form note about a home (or a specific item). A WRITE — proposed for approval. Use for 'remember that…', 'make a note that…'.", "properties": { "tool": { "const": "create_note" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "body": { "type": "string", "description": "The note text." }, "title": { "type": "string", "description": "Optional short title." }, "item_id": { "type": "string", "description": "Optional inventory item id to attach it to." } }, "required": [ "body" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.notes", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateNoteCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing note's text or title. Get its id from list_notes first. A WRITE — proposed for approval.", "properties": { "tool": { "const": "update_note" }, "args": { "type": "object", "properties": { "note_id": { "type": "string", "description": "The note id (from list_notes)." }, "body": { "type": "string", "description": "The new note text." }, "title": { "type": "string", "description": "New title, if changing." } }, "required": [ "note_id", "body" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.notes", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateExpenseCall": { "type": "object", "required": [ "tool" ], "description": "Record a home expense (a payment or a purchase) — also mirrored onto the Timeline. A WRITE — proposed for approval. Gather the amount, what it was for, and roughly when.", "properties": { "tool": { "const": "create_expense" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "amount": { "type": "number", "description": "Amount in dollars." }, "category": { "type": "string", "description": "One of: utilities, repairs, maintenance, improvements, kitchen, bathroom, roof, hvac, windows-doors, solar-energy, flooring, landscaping, addition, services, insurance, taxes, mortgage, supplies, other. Use 'other' if unsure." }, "description": { "type": "string", "description": "What it was for, e.g. \"Water heater repair\"." }, "spent_at": { "type": "string", "description": "When (ISO date). Omit for today." }, "payee": { "type": "string", "description": "Who was paid." }, "item_id": { "type": "string", "description": "Optional inventory item id it relates to." }, "vendor_contact_id": { "type": "string", "description": "Optional contact id of the vendor (from list_contacts)." }, "is_investment": { "type": "boolean", "description": "Is this money that went INTO the house rather than just running it — a new roof, a remodel, a replaced furnace? Those go on the Investment ledger and count toward cost basis; routine bills and repairs do not. Ask the user if it is a large or improvement-shaped expense and you are unsure. Leave it out to let the category decide." } }, "required": [ "amount", "category" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.expenses", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateExpenseCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing expense — correct its amount, category, description, or date, or link a vendor. First call list_expenses to get the real expense id from its 'largest entries' list; never invent an id. A WRITE — proposed for approval.", "properties": { "tool": { "const": "update_expense" }, "args": { "type": "object", "properties": { "expense_id": { "type": "string", "description": "The real expense id (a UUID from list_expenses). Do not make one up." }, "amount": { "type": "number", "description": "New amount in dollars." }, "category": { "type": "string", "description": "One of: utilities, repairs, maintenance, improvements, kitchen, bathroom, roof, hvac, windows-doors, solar-energy, flooring, landscaping, addition, services, insurance, taxes, mortgage, supplies, other. Use 'other' if unsure." }, "description": { "type": "string", "description": "New description." }, "spent_at": { "type": "string", "description": "New date (ISO)." }, "payee": { "type": "string", "description": "Who was paid." }, "vendor_contact_id": { "type": "string", "description": "Link the expense to this vendor/contact id (from list_contacts)." }, "is_investment": { "type": "boolean", "description": "Mark this expense as money that went INTO the house (a new roof, a remodel, a replaced furnace) so it lands on the Investment ledger, or false to take it back off. Leave it out to leave it as it is." } }, "required": [ "expense_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.expenses", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateMortgageCall": { "type": "object", "required": [ "tool" ], "description": "Record a home's mortgage (loan) details. A WRITE — proposed for approval. A home has at most one mortgage; check get_mortgage first. Gather lender, principal, rate, term, and start date.", "properties": { "tool": { "const": "create_mortgage" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "lender": { "type": "string", "description": "Lender name." }, "original_principal": { "type": "number", "description": "Original loan amount, in dollars." }, "interest_rate_pct": { "type": "number", "description": "Interest rate percent, e.g. 6.25." }, "term_months": { "type": "number", "description": "Term in months, e.g. 360." }, "start_date": { "type": "string", "description": "Loan start date (ISO)." }, "estimated_value": { "type": "number", "description": "Optional current home value estimate." }, "purchase_price": { "type": "number", "description": "Optional purchase price." } }, "required": [ "original_principal", "interest_rate_pct", "term_months", "start_date" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.mortgage", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateMortgageCall": { "type": "object", "required": [ "tool" ], "description": "Edit a home's mortgage — update the lender, rate, balance, or current value estimate. Get its id from get_mortgage first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_mortgage" }, "args": { "type": "object", "properties": { "mortgage_id": { "type": "string", "description": "The mortgage id (from get_mortgage)." }, "lender": { "type": "string", "description": "Lender name." }, "interest_rate_pct": { "type": "number", "description": "Interest rate percent." }, "estimated_value": { "type": "number", "description": "Current home value estimate." }, "current_balance_override": { "type": "number", "description": "Latest statement balance." } }, "required": [ "mortgage_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.mortgage", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateWarrantyCall": { "type": "object", "required": [ "tool" ], "description": "Record a warranty or service contract on an inventory item (find the item first with search_inventory to get its id). A WRITE — proposed for approval. List existing warranties first to avoid duplicates.", "properties": { "tool": { "const": "create_warranty" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "item_id": { "type": "string", "description": "The covered item id (from search_inventory). Required." }, "type": { "type": "string", "description": "'manufacturer' (default), 'extended', or 'service_contract'." }, "provider": { "type": "string", "description": "Who backs it, e.g. \"GE\", \"Asurion\", \"AppleCare\"." }, "contract_number": { "type": "string", "description": "Warranty / contract number, if any." }, "start_date": { "type": "string", "description": "Coverage start (ISO date)." }, "end_date": { "type": "string", "description": "Coverage end / expiry (ISO date)." }, "coverage": { "type": "string", "description": "What it covers, in brief." }, "claim_phone": { "type": "string", "description": "Claims phone." }, "claim_email": { "type": "string", "description": "Claims email." }, "claim_url": { "type": "string", "description": "Claims website." }, "cost": { "type": "number", "description": "What an extended warranty / service contract cost." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "item_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.warranty", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateWarrantyCall": { "type": "object", "required": [ "tool" ], "description": "Edit an existing warranty — fix its provider, dates, coverage, or claim details. Get its id from list_warranties first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_warranty" }, "args": { "type": "object", "properties": { "warranty_id": { "type": "string", "description": "The warranty id (from list_warranties)." }, "type": { "type": "string", "description": "'manufacturer' (default), 'extended', or 'service_contract'." }, "provider": { "type": "string", "description": "Who backs it, e.g. \"GE\", \"Asurion\", \"AppleCare\"." }, "contract_number": { "type": "string", "description": "Warranty / contract number, if any." }, "start_date": { "type": "string", "description": "Coverage start (ISO date)." }, "end_date": { "type": "string", "description": "Coverage end / expiry (ISO date)." }, "coverage": { "type": "string", "description": "What it covers, in brief." }, "claim_phone": { "type": "string", "description": "Claims phone." }, "claim_email": { "type": "string", "description": "Claims email." }, "claim_url": { "type": "string", "description": "Claims website." }, "cost": { "type": "number", "description": "What an extended warranty / service contract cost." }, "notes": { "type": "string", "description": "Any extra detail." } }, "required": [ "warranty_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.warranty", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateTaskCall": { "type": "object", "required": [ "tool" ], "description": "Add a to-do task for a home — e.g. the user says \"remind me to service the furnace\" or \"add a task to reseal the deck\". A WRITE — proposed for approval, so don't say it's already added. A due date is optional; a task with one also shows on the Calendar.", "properties": { "tool": { "const": "create_task" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "title": { "type": "string", "description": "The task, short and actionable. e.g. \"Service furnace\"." }, "description": { "type": "string", "description": "Optional extra detail." }, "priority": { "type": "string", "description": "Optional: 'low', 'medium', or 'high'." }, "due_at": { "type": "string", "description": "Optional due date/time (ISO, e.g. 2026-10-01)." }, "item_id": { "type": "string", "description": "Optional inventory item id it relates to (from search_inventory)." }, "room_id": { "type": "string", "description": "Optional room id it relates to (from list_floors)." } }, "required": [ "title" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "activity.tasks", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateTaskCall": { "type": "object", "required": [ "tool" ], "description": "Edit or complete an existing task — mark it done, reschedule it, or change its priority. Get its id from list_tasks first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_task" }, "args": { "type": "object", "properties": { "task_id": { "type": "string", "description": "The task id (from list_tasks)." }, "title": { "type": "string", "description": "New title, if renaming." }, "description": { "type": "string", "description": "New detail." }, "status": { "type": "string", "description": "'open', 'snoozed', 'done', or 'dismissed'." }, "priority": { "type": "string", "description": "'low', 'medium', or 'high'." }, "due_at": { "type": "string", "description": "New due date/time (ISO)." } }, "required": [ "task_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "activity.tasks", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateCalendarEventCall": { "type": "object", "required": [ "tool" ], "description": "Put a dated event on a home's calendar — e.g. \"schedule the inspection for Oct 3\" or \"add the property-tax deadline\". A WRITE — proposed for approval. Needs a start date/time.", "properties": { "tool": { "const": "create_calendar_event" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "title": { "type": "string", "description": "What the event is, e.g. \"Home inspection\"." }, "starts_at": { "type": "string", "description": "When it starts (ISO date or datetime)." }, "ends_at": { "type": "string", "description": "Optional end (ISO)." }, "all_day": { "type": "boolean", "description": "True for an all-day deadline with no specific time." }, "type": { "type": "string", "description": "Optional kind: maintenance, tax_deadline, warranty_expiry, bill_due, cleaning, inspection, renewal, custom." }, "description": { "type": "string", "description": "Optional detail." }, "item_id": { "type": "string", "description": "Optional related inventory item id." }, "room_id": { "type": "string", "description": "Optional related room id." } }, "required": [ "title", "starts_at" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "activity.calendar", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateCalendarEventCall": { "type": "object", "required": [ "tool" ], "description": "Edit or cancel a calendar event — move its date, rename it, or cancel it. Get its id from list_calendar_events first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_calendar_event" }, "args": { "type": "object", "properties": { "event_id": { "type": "string", "description": "The event id (from list_calendar_events)." }, "title": { "type": "string", "description": "New title." }, "starts_at": { "type": "string", "description": "New start (ISO)." }, "ends_at": { "type": "string", "description": "New end (ISO)." }, "all_day": { "type": "boolean", "description": "All-day?" }, "type": { "type": "string", "description": "New kind." }, "description": { "type": "string", "description": "New detail." }, "status": { "type": "string", "description": "'scheduled' or 'cancelled'." } }, "required": [ "event_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "activity.calendar", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateFloorCall": { "type": "object", "required": [ "tool" ], "description": "Add a floor / level to a home (e.g. \"add a basement\" or \"add a second floor\"). A WRITE — proposed for approval. List floors first to avoid duplicates.", "properties": { "tool": { "const": "create_floor" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "Floor name, e.g. \"Ground Floor\", \"Basement\"." }, "level": { "type": "number", "description": "Vertical order: basement -1, ground 0, upstairs +1, etc." }, "kind": { "type": "string", "description": "Optional kind, e.g. basement, main, upper, attic." }, "notes": { "type": "string", "description": "Optional notes." }, "area_sqft": { "type": "number", "description": "Optional area in square feet." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.profile", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateFloorCall": { "type": "object", "required": [ "tool" ], "description": "Edit a floor — rename it, reorder it, or set its area. Get its id from list_floors first. A WRITE — proposed for approval.", "properties": { "tool": { "const": "update_floor" }, "args": { "type": "object", "properties": { "floor_id": { "type": "string", "description": "The floor id (from list_floors)." }, "name": { "type": "string", "description": "New name." }, "level": { "type": "number", "description": "New vertical order." }, "kind": { "type": "string", "description": "New kind." }, "notes": { "type": "string", "description": "New notes." }, "area_sqft": { "type": "number", "description": "Area in square feet." } }, "required": [ "floor_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.profile", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateRoomCall": { "type": "object", "required": [ "tool" ], "description": "Add a room / space to a home (e.g. \"add a Primary Bedroom\" or \"add the garage\"). A WRITE — proposed for approval. List floors/rooms first to avoid duplicates.", "properties": { "tool": { "const": "create_room" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "Room name, e.g. \"Primary Bedroom\", \"Garage\"." }, "type": { "type": "string", "description": "Optional: kitchen, bedroom, bathroom, living, dining, garage, office, laundry, basement, attic, outdoor, storage, other." }, "floor_id": { "type": "string", "description": "Optional floor id it sits on (from list_floors)." }, "dimensions_sqft": { "type": "number", "description": "Optional floor area in square feet." }, "notes": { "type": "string", "description": "Optional notes." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.inventory", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateRoomCall": { "type": "object", "required": [ "tool" ], "description": "Edit a room — rename it, set its type/floor/area. Get its id from list_floors (which lists each floor's rooms). A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_room" }, "args": { "type": "object", "properties": { "room_id": { "type": "string", "description": "The room id (from list_floors)." }, "name": { "type": "string", "description": "New name." }, "type": { "type": "string", "description": "New room type." }, "floor_id": { "type": "string", "description": "Move to this floor id." }, "dimensions_sqft": { "type": "number", "description": "Floor area in square feet." }, "notes": { "type": "string", "description": "New notes." } }, "required": [ "room_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "home.inventory", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CompleteMaintenanceCall": { "type": "object", "required": [ "tool" ], "description": "Mark a recurring maintenance plan done — use it when the user says they (or someone) did a job the home has a plan for: \"changed the furnace filter\", \"finally cleared the gutters\", \"Joe came and did the yearly HVAC thing\", \"paid the gutter guys $180 to do the gutters\". Pick the plan from the ones you have been shown (the account overview lists each home's plans; list_maintenance gives the full list with ids) — only ever pass an id you have actually seen. If two plans could fit, ASK which one rather than guessing. If it is maintenance but NO plan fits, do not force it: log_activity records what happened, and you can offer to set the job up as a recurring plan with create_maintenance_plan. Include the cost in the same call when the user mentions one — do not also call log_expense, this handles it. This is a WRITE: it becomes an approval card, so don't say it is done.", "properties": { "tool": { "const": "complete_maintenance" }, "args": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The maintenance plan's id, from list_maintenance or the account overview. Never invent one." }, "occurred_at": { "type": "string", "description": "When it was done (ISO date, e.g. 2026-08-08). Omit for today." }, "cost": { "type": "number", "description": "What it cost, in dollars, if the user said. Omit when they did it themselves or did not mention money." }, "vendor": { "type": "string", "description": "Who did the work, if the user named someone." }, "notes": { "type": "string", "description": "Anything extra worth recording about this particular time." } }, "required": [ "plan_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.maintenance", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateMaintenancePlanCall": { "type": "object", "required": [ "tool" ], "description": "Set up a recurring maintenance plan for a home — use it when the user asks for one, or when they tell you they did a job that has no plan yet and they accept your offer to make it recurring (\"want me to make that a filter change every 3 months?\"). Check list_maintenance first so you do not create a second plan for something the home already tracks. Marking the job itself done is complete_maintenance, and it needs a plan to exist first. This is a WRITE: it becomes an approval card, so don't say it is done.", "properties": { "tool": { "const": "create_maintenance_plan" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "title": { "type": "string", "description": "What the job is, in the user's words. e.g. \"Change the HVAC filter\"." }, "every_n": { "type": "number", "description": "How often, as a number. e.g. 3 for every 3 months." }, "unit": { "type": "string", "description": "The interval unit: 'day', 'week', 'month' or 'year'." }, "starts_on": { "type": "string", "description": "The date the schedule counts from (ISO date) — usually the last time it was done. Omit for today." }, "item_id": { "type": "string", "description": "Optional inventory item this plan is for (from search_inventory), e.g. the furnace." }, "room_id": { "type": "string", "description": "Optional room this plan is for (from list_floors)." }, "notes": { "type": "string", "description": "Anything worth remembering about the job." } }, "required": [ "title", "every_n", "unit" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.maintenance", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateMaintenancePlanCall": { "type": "object", "required": [ "tool" ], "description": "Change a recurring maintenance plan that already exists — how often it runs, when it counts from, its notes, its priority, or whether it is paused. Find it with list_maintenance first so you have its id. Use `active: false` to PAUSE a plan (it stops being due and stops generating work) and `active: true` to resume it. Marking a job DONE is complete_maintenance, not this. Pass only the fields that change; everything else is left alone. A WRITE — proposed for approval.", "properties": { "tool": { "const": "update_maintenance_plan" }, "args": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "The plan's id from list_maintenance." }, "title": { "type": "string", "description": "Rename the job." }, "every_n": { "type": "number", "description": "How often, as a number. e.g. 3 for every 3 months." }, "unit": { "type": "string", "description": "The interval unit: 'day', 'week', 'month' or 'year'." }, "starts_on": { "type": "string", "description": "Re-anchor the schedule to this date (ISO date)." }, "notes": { "type": "string", "description": "Replace the notes on the plan." }, "priority": { "type": "string", "description": "'low', 'medium' or 'high'." }, "active": { "type": "boolean", "description": "false pauses the plan; true resumes it." } }, "required": [ "plan_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.maintenance", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "CreateInsurancePolicyCall": { "type": "object", "required": [ "tool" ], "description": "Record an insurance policy on a home — homeowners, flood, umbrella, auto, boat, appliance coverage. Check list_insurance first so you do not record a second copy of a policy the home already has. If the user shared a photo of a declarations page or an insurance card, read the details off it first. A WRITE — proposed for approval, so do not say it is saved until the card is approved.", "properties": { "tool": { "const": "create_insurance_policy" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "type": { "type": "string", "description": "One of: home, flood, umbrella, appliance, auto, motor, boat. Use 'custom' for anything else." }, "insurer": { "type": "string", "description": "The company that backs it, e.g. \"State Farm\"." }, "policy_number": { "type": "string", "description": "The policy number." }, "insured_asset": { "type": "string", "description": "What it insures, in the user's words — \"the house\", \"the 2019 Subaru\"." }, "coverage_amount": { "type": "number", "description": "Coverage limit in dollars." }, "deductible": { "type": "number", "description": "Deductible in dollars." }, "premium": { "type": "number", "description": "What the premium costs, in dollars." }, "premium_period": { "type": "string", "description": "How often the premium is billed: 'monthly', 'quarterly', 'annual', 'one_time'." }, "effective_date": { "type": "string", "description": "When coverage starts (ISO date)." }, "expiration_date": { "type": "string", "description": "When coverage ends (ISO date)." }, "renewal_date": { "type": "string", "description": "Renewal date (ISO date)." }, "claim_phone": { "type": "string", "description": "Claims phone number." }, "claim_url": { "type": "string", "description": "Claims website." }, "notes": { "type": "string", "description": "Anything else worth keeping." } }, "required": [ "type" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.insurance", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UpdateInsurancePolicyCall": { "type": "object", "required": [ "tool" ], "description": "Change an insurance policy already on record — a renewal, a new premium, a changed deductible or claims number. Find it with list_insurance first so you have its id. Pass only the fields that change; everything else is left alone. A WRITE — proposed for approval.", "properties": { "tool": { "const": "update_insurance_policy" }, "args": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "The policy's id from list_insurance." }, "type": { "type": "string", "description": "One of: home, flood, umbrella, appliance, auto, motor, boat. Use 'custom' for anything else." }, "insurer": { "type": "string", "description": "The company that backs it, e.g. \"State Farm\"." }, "policy_number": { "type": "string", "description": "The policy number." }, "insured_asset": { "type": "string", "description": "What it insures, in the user's words — \"the house\", \"the 2019 Subaru\"." }, "coverage_amount": { "type": "number", "description": "Coverage limit in dollars." }, "deductible": { "type": "number", "description": "Deductible in dollars." }, "premium": { "type": "number", "description": "What the premium costs, in dollars." }, "premium_period": { "type": "string", "description": "How often the premium is billed: 'monthly', 'quarterly', 'annual', 'one_time'." }, "effective_date": { "type": "string", "description": "When coverage starts (ISO date)." }, "expiration_date": { "type": "string", "description": "When coverage ends (ISO date)." }, "renewal_date": { "type": "string", "description": "Renewal date (ISO date)." }, "claim_phone": { "type": "string", "description": "Claims phone number." }, "claim_url": { "type": "string", "description": "Claims website." }, "notes": { "type": "string", "description": "Anything else worth keeping." } }, "required": [ "policy_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.insurance", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "RunIrrigationZoneCall": { "type": "object", "required": [ "tool" ], "description": "Start watering ONE irrigation zone now, for a set number of minutes. Pass the zone NAME as the user said it — it is matched against the home's zones for you, and you will be told to ask if it is ambiguous or unknown, so you do not need an id. A WRITE, and a physical one — it is proposed for approval and the water only runs once the user approves. Ask how long if they did not say; do not guess a duration.", "properties": { "tool": { "const": "run_irrigation_zone" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "zone": { "type": "string", "description": "The zone's name, as the user said it (e.g. \"the rose bed\"). Pass this whenever you have a name — it is matched against the home's zones, and you are asked which one if it is ambiguous." }, "zone_id": { "type": "string", "description": "The zone's id, if you have one from list_irrigation_zones in THIS turn. Optional — a name is enough." }, "minutes": { "type": "number", "description": "How long to water, in minutes (1–180)." } }, "required": [ "minutes" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.irrigation", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "StopIrrigationZoneCall": { "type": "object", "required": [ "tool" ], "description": "Stop watering now. Pass the zone NAME as the user said it; an id is not needed. A WRITE — proposed for approval. Note that most controllers stop water at the device, so this may end any zone currently running on that controller, not only the one named.", "properties": { "tool": { "const": "stop_irrigation_zone" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "zone": { "type": "string", "description": "The zone's name, as the user said it. A name is enough." }, "zone_id": { "type": "string", "description": "The zone's id, if you have one. Optional." } }, "required": [] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "record:write", "x-casa-kind": "action", "x-casa-module": "tools.irrigation", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "AttachFileCall": { "type": "object", "required": [ "tool" ], "description": "File a photo or document the user shared in THIS chat onto a record, so it's kept with that record. Use when the user shares a file and wants it saved with something — e.g. \"here's the receipt for the water heater\" (item), \"here's the warranty certificate for the fridge\" (warranty), \"here's my homeowners policy / declarations page / insurance card\" (insurance), \"here's the service report for the annual boiler check\" (maintenance), \"add this photo to my plumber\" (contact), \"here's the receipt for that $200 expense\" (expense), \"attach this to my 'reseal deck' task\", \"save this to my house\" (home), \"file this under my mortgage\". Unless the target is the home, first look up its id with the matching data tool (search_inventory / list_contacts / list_services / get_mortgage / list_warranties / list_insurance / list_maintenance / list_tasks / list_expenses). The shared file is used automatically — you don't pass it. A WRITE — proposed for approval. (To save a file loosely into the Files tool without tying it to a record, use upload_to_files instead.) Use target_type \"timeline\" with a Timeline entry's id to file a photo onto something already logged. You do NOT need this tool for a record you just created in this same turn — a shared photo is filed onto it automatically.", "properties": { "tool": { "const": "attach_file" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "target_type": { "type": "string", "description": "What to file it on: item, contact, service, home, mortgage, warranty, insurance, maintenance, task, expense, or timeline." }, "target_id": { "type": "string", "description": "The record's id from the matching data tool (search_inventory / list_contacts / list_services / get_mortgage / list_tasks / list_expenses). Omit only for 'home'." } }, "required": [ "target_type" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "files:write", "x-casa-kind": "action", "x-casa-module": "tools.files", "x-casa-capability": "create", "x-casa-confirm": "always" }, "UploadToFilesCall": { "type": "object", "required": [ "tool" ], "description": "Save a photo or document the user shared in THIS chat into the home's Files, filed in the right folder — when the user wants to keep a file rather than tie it to one record. E.g. \"save this to my Files\", \"file this away\", \"put this in my Warranties folder\", \"keep this document\". ALWAYS choose a `folder` from the list in that argument based on what the document IS; only leave it out when nothing fits. If the account has more than one home and the user did not say which, ASK — do not guess which house a document belongs to. The shared file is used automatically. A WRITE — proposed for approval.", "properties": { "tool": { "const": "upload_to_files" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "folder": { "type": "string", "description": "Which folder this document belongs in, chosen from what it IS. One of: Finance — Money matters for the home — statements, bills, and tax records.; Finance / Mortgage — Loan statements, amortization, and refinance paperwork.; Finance / Property Tax — Assessments and property-tax bills.; Finance / Expenses & Receipts — Receipts and invoices for home spending.; Finance / Closing Documents — The purchase closing packet — deed, title, settlement.; Items — Manuals, warranties, and receipts for your things. A subfolder is created per item as documents are added.; Warranties — Warranty certificates and coverage documents.; Insurance — Policies, declarations pages, ID cards, and claims — home, auto, umbrella, and more.; Services — Contracts and bills for utilities, internet, lawn, cleaning, and coverage.; Maintenance — Service records, inspections, and repair reports.; Contacts — Documents tied to a person or company. A subfolder per contact appears as needed.; Manuals — Product manuals and how-to guides.; Inspections & Permits — Inspection reports and building permits.; Photos — Photos of the home and its contents.; Other — Anything without a home yet.. Use the exact name shown (a nested one as \"Finance / Mortgage\"). Leave it out only if none of them fit." }, "folder_id": { "type": "string", "description": "A specific folder id from list_folders — use this only when the user named a folder that is not in the standard list above." } } }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "files:write", "x-casa-kind": "action", "x-casa-module": "tools.files", "x-casa-capability": "create", "x-casa-confirm": "always" }, "CreateFolderCall": { "type": "object", "required": [ "tool" ], "description": "Create a folder in a home's Files to organize documents (e.g. \"make an HVAC folder\"). A WRITE — proposed for approval. List folders first to avoid duplicates. This makes a folder only — it does not upload files.", "properties": { "tool": { "const": "create_folder" }, "args": { "type": "object", "properties": { "home": { "type": "string", "description": "Which home — its name. Omit only if the account has one home." }, "name": { "type": "string", "description": "Folder name, e.g. \"Warranties\"." }, "parent_id": { "type": "string", "description": "Optional parent folder id (from list_folders) to nest under." }, "purpose": { "type": "string", "description": "Optional short description of what goes in it." } }, "required": [ "name" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "files:write", "x-casa-kind": "action", "x-casa-module": "tools.files", "x-casa-capability": "create", "x-casa-confirm": "auto" }, "UpdateFolderCall": { "type": "object", "required": [ "tool" ], "description": "Rename a folder or change its description. Get its id from list_folders first. A WRITE — proposed for approval. Only pass what's changing.", "properties": { "tool": { "const": "update_folder" }, "args": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "The folder id (from list_folders)." }, "name": { "type": "string", "description": "New name." }, "purpose": { "type": "string", "description": "New description." } }, "required": [ "folder_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "files:write", "x-casa-kind": "action", "x-casa-module": "tools.files", "x-casa-capability": "edit", "x-casa-confirm": "always" }, "ReadMemoryCall": { "type": "object", "required": [ "tool" ], "description": "Read one page of the Agent's Mind in full by node_id, plus its directly-connected pages. Ids come from the index at GET /api/agent/external/mind. Served redacted, like the index.", "properties": { "tool": { "const": "read_memory" }, "args": { "type": "object", "properties": { "node_id": { "type": "string" } }, "required": [ "node_id" ] }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Files to store with what the tool creates. Needs the `files:write` scope as well." }, "correlationId": { "type": "string", "maxLength": 200 }, "ownerConfirmed": { "type": "boolean", "description": "Your assertion that a person approved this call. Recorded on the Activity entry; never trusted, never widens what the key may do." } }, "x-casa-scope": "mind:read", "x-casa-kind": "mind", "x-casa-module": null, "x-casa-capability": null, "x-casa-confirm": null } } }, "x-casa-scopes": [ { "scope": "record:read", "grants": "Read the home record — inventory, contacts, expenses, files, and the rest." }, { "scope": "record:write", "grants": "Create and update records. Never delete." }, { "scope": "files:write", "grants": "Attach files to records, upload into Files, and organise folders." }, { "scope": "mind:read", "grants": "Read the Agent's Mind — the rendered, redacted index, and one page in full." }, { "scope": "mind:suggest", "grants": "Propose a memory to the Agent. The Agent decides whether to write it." } ], "x-casa-limits": { "callsPerMinutePerKey": 60, "suggestionsPerMinutePerAccount": 10, "maxAttachmentsPerCall": 5, "maxAttachmentBytes": 10485760 } }