# HOA Maintenance Calendar Builder

> Build a practical year of maintenance planning, then adjust it to your community.

Human page: https://tools.rodri.ai/tools/maintenance-calendar
Skill: https://tools.rodri.ai/.well-known/skills/maintenance-calendar/SKILL.md
Category: coordination
Exports: text, csv, print

## Operations

| Operation | Engine | Cost |
| --- | --- | --- |
| `maintenance_calendar.build` | deterministic | free, no key |
| `maintenance_calendar.suggest` | ai | 1 AI credit |

### `maintenance_calendar.build`

Build maintenance plan. No credential needed. Deterministic arithmetic, so it costs no allowance and is rate limited by address.

Input schema version 1, output schema version 1.
MCP tool name: `maintenance_calendar_build`

Input JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "communityName": {
      "type": "string",
      "maxLength": 120
    },
    "planStartDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "timeZone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "assets": {
      "default": [],
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "roofs_drainage",
          "grounds_irrigation",
          "lighting",
          "gates_access",
          "shared_hvac",
          "pool_amenities",
          "elevators",
          "fire_life_safety"
        ]
      }
    },
    "seasonalMonths": {
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 12
      }
    },
    "climateNote": {
      "type": "string",
      "maxLength": 400
    },
    "tasks": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 64
          },
          "assetId": {
            "type": "string",
            "enum": [
              "roofs_drainage",
              "grounds_irrigation",
              "lighting",
              "gates_access",
              "shared_hvac",
              "pool_amenities",
              "elevators",
              "fire_life_safety",
              "custom"
            ]
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "description": {
            "type": "string",
            "maxLength": 400
          },
          "responsibleLabel": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 80
              },
              {
                "type": "null"
              }
            ]
          },
          "origin": {
            "type": "string",
            "enum": [
              "user",
              "template",
              "source",
              "ai_suggestion"
            ]
          },
          "scheduleBasis": {
            "type": "string",
            "enum": [
              "user_supplied",
              "source_supported",
              "suggested"
            ]
          },
          "firstDueDate": {
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  {
                    "type": "string",
                    "const": ""
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "recurrence": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "unit": {
                    "type": "string",
                    "enum": [
                      "week",
                      "month"
                    ]
                  },
                  "interval": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 52
                  },
                  "monthDayPolicy": {
                    "type": "string",
                    "enum": [
                      "anchor_day_clamped",
                      "last_day"
                    ]
                  }
                },
                "required": [
                  "unit",
                  "interval"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "reviewItems": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 200
            }
          },
          "specialistRequired": {
            "type": "boolean"
          },
          "sourceCitationIds": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 64
            }
          }
        },
        "required": [
          "assetId",
          "title"
        ]
      }
    },
    "includeTemplates": {
      "default": true,
      "type": "boolean"
    },
    "overrides": {
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string",
            "maxLength": 64
          },
          "originalDueDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "currentDueDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "excluded": {
            "type": "boolean"
          }
        },
        "required": [
          "taskId",
          "originalDueDate"
        ]
      }
    },
    "locale": {
      "default": "en",
      "type": "string",
      "enum": [
        "en",
        "es"
      ]
    }
  },
  "required": [
    "planStartDate",
    "timeZone"
  ]
}
```

### `maintenance_calendar.suggest`

Suggest additions with AI. Needs an API key. Spends 1 AI credit from the key owner's monthly allowance.

Input schema version 1, output schema version 1.
MCP tool name: `maintenance_calendar_suggest`

Input JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "notes": {
      "type": "string",
      "maxLength": 20000
    },
    "sourceSetId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "sourceSetVersion": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "locale": {
      "default": "en",
      "type": "string",
      "enum": [
        "en",
        "es"
      ]
    }
  },
  "required": [
    "runId"
  ]
}
```

### Running an operation

Two ways in, and the difference is what an operation costs.

**No credential.** The four calculators are pure arithmetic — no model, nothing
stored, no allowance spent. Rate limited to 30 requests a minute per address.

```http
POST https://tools.rodri.ai/api/agent/tools/{toolId}/runs
Content-Type: application/json

{"operation": "meeting_quorum.calculate", "input": { ... }}
```

**With an API key.** Everything else, including every AI operation. The key's
owner creates it at https://tools.rodri.ai/account. It carries exactly their entitlements: a
free account has 20 AI credits a month and unlimited use of the calculators.
A key grants nothing its owner does not already have.

```http
POST https://tools.rodri.ai/api/agent/tools/{toolId}/runs
Authorization: Bearer hpt_live_…
Content-Type: application/json

{"operation": "resident_notice.generate", "input": { ... }}
```

Errors come back as `{"error": {"code", "message", "retryable"}}`. Branch on
`code` — `QUOTA_EXHAUSTED`, `RATE_LIMITED`, `REGISTRATION_REQUIRED`,
`VALIDATION_ERROR` — not on the sentence, which is written for people and is
translated.

**MCP.** The same operations are exposed at `https://tools.rodri.ai/api/mcp` over Streamable
HTTP. It is stateless, so POST JSON-RPC and read the JSON reply; the same
`Authorization` header applies.