Skip to main content
Glama

Sync new or changed building permits

get_permits_sync
Read-onlyIdempotent

Building permits that are new to this account or changed since the last delivery. limit is required. The cursor from the previous page continues the walk; updatedSince (ISO 8601) starts it at a time; with neither, the walk is full. Send one of cursor or updatedSince, not both. sort, offset, and permitIds are not accepted. Otherwise the same filters as search_permits; changing them starts a new walk. Each new or changed permit counts toward 100,000 export records a month on County, State, and National plans. On API Only and the trial, costs 1 credit per new or changed permit. An unchanged permit already delivered does not use credits. A permit that leaves Boardwalk stops appearing and get_permit returns 404 for it. get_credit_balance returns the remaining balance. contactWithheld on a private individual means the phone or email exists but is withheld: "upgrade" (homeowner phones and emails need a paid plan, and the user's plan does not include them) or "acknowledge" (the user accepts the homeowner contact rules once in the Boardwalk web app). It is never missing. "[phone withheld]" and "[email withheld]" in titles, summaries, or notes (textContactWithheld) are the same rule and can hide business lines too. Name every party; mention withholding only for a party that carries contactWithheld.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "limit": "<limit>"
    },
    "name": "get_permits_sync"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSame as the permits map search box: words from the permit (work description, address, names) or a permit number. One search text, not a list: for several alternative terms, make one call per term. Use one of q, permitNumber, or contractor per call.
idsNoAlias of permitIds.
bboxNoMap area as "west,south,east,north" or {west,south,east,north}. Around a planned project, search q with its street address first; use a small box around its coordinates only when it has no address, and say which permits are at neighbouring addresses.
limitYesRequired. Number of records to return, 1-25. Each new or changed record counts toward 100,000 export records a month. An unchanged record already delivered does not.
citiesNoRegion: city ids or names ("Lehi"). A permit in any listed state, county, or city matches, so do not add the county. A name that matches several cities is refused with each candidate's id and state: pass the id, or add the state (states:["UT"]), which then only helps find the city.
cursorNoOpaque cursor from the previous sync page (meta.nextCursor). Not with updatedSince.
dateToNoWindow end, YYYY-MM-DD, inclusive.
stagesNoStatus stage as "<status>:<stage>" or "bucket:<status>"; get_permit_reference facet "stages" lists them.
statesNoRegion: state ids, names, or abbreviations ("UT"). states, counties, and cities are one Region filter: a permit in any of them matches. Send only the narrowest place, never "UT" together with "Utah County".
tradesNoTrades the job involves (the scope of the work, not open bids): site_work, foundation, paving_concrete, framing, roofing, windows_doors, siding_exterior, insulation, electrical, plumbing, hvac, gas, fire_protection, low_voltage, solar, elevator, drywall, flooring, cabinets_countertops, finish_carpentry, painting, appliances, cleaning, landscaping, fencing, pool. roofing here also matches new homes and additions with roof work; workTypes roofing is re-roof jobs only. When a trade rep asks for "roofing permits", count both and say which is which.
whyNowNoWhy now codes: issued_no_inspections, rough_in_passed, finals_next, last_inspection_failed, on_hold, fees_due, slow_review, new_owner, expiring_soon.
sectorsNoPrivate or public work. Default both.
sqftMaxNoSquare feet maximum.
sqftMinNoSquare feet minimum.
countiesNoRegion: county ids or names ("Utah County"). Names that match more than one place are refused, not guessed; the refusal lists each candidate's id and state. A permit in any listed state, county, or city matches. A state sent with a county inside it only helps find the county (warning region_parent_state_dropped).
dateFromNoWindow start, YYYY-MM-DD, inclusive.
jobKindsNoMajor or minor jobs. Default both; "major" alone leaves out small jobs such as a water heater swap.
placeKeyNoplaceKey from a permit: every permit at that address (at most 20 keys).
statusesNoStatus: in_review (applied or approved, not issued yet), active (issued, under way, or on hold), final (completed or closed), inactive (ended without a final: expired, withdrawn, denied, void, or stopped), no_construction (a record with no construction work).
unitsMaxNoUnits maximum.
unitsMinNoUnits minimum (homes or apartments on the permit).
valueMaxNoJob value maximum in dollars.
valueMinNoJob value minimum in dollars, as stated on the permit. "Over $50k" → 50000.
dateFieldNoWhich date the window applies to: applied, issued, or activity (latest activity, the default).
dateRangeNoDate window. Defaults to 12m. "all" removes the window.
permitIdsNoExact permit ids to re-read, at most 100. No default date window applies. Unchanged permits already delivered are not charged again.
workTypesNoWork type keys: new_home, multifamily, adu, manufactured, new_commercial, new_other, addition, interior_remodel, kitchen_bath, tenant_improvement, accessory, structural_repair, repair, hvac, electrical, solar_battery, generator, plumbing, water_heater, gas, fire_protection, telecom, roofing, windows_doors, siding, pool, fence, signage, demolition, grading, utilities, driveway_sidewalk, septic_well, planning, unspecified. A work type is what the job is: roofing = a re-roof or roof repair job. For every job that includes a trade (a new home includes roofing), use trades.
contractorNoA contractor's full name, e.g. "Acme Roofing". Case, punctuation, and endings such as LLC, Inc., Corp., Co., and Ltd. are ignored, so "acme roofing" also finds "Acme Roofing, LLC". Every other word counts, so part of a name ("Acme") matches nothing. When unsure of the name, call search_permit_contractors (q with the name words) and pass its contractorKeys.
detailOnlyNoOnly permits whose full detail page was read.
valueBandsNoValue bands: u10k (under $10k), 10k, 50k, 250k, 1m (and up).
workGroupsNoWork type groups: new (new homes and buildings), remodel, systems, exterior, site, planning, unspecified.
assetClassesNoBuilding type class (3rd level), e.g. Single-Family Home.
permitNumberNoAn exact permit number, e.g. "BLD-2025-01234". Searches every date unless you send a date filter.
updatedSinceNoISO 8601 time to start the walk from, e.g. "2026-10-01T00:00:00Z".
hasAnyContactNoOnly permits with any phone or email, private individuals included.
hasContractorNoOnly permits that name a contractor.
propertyTypesNoBuilding type, the same labels as planned projects (get_project_types): Residential, Commercial, …
contractorKeysNoExact contractor keys from search_permit_contractors (at most 50). Every permit by those contractors.
hasInspectionsNoOnly permits with at least one inspection that has a result (passed, failed, or completed).
includeRecordsNoAlso return non-job records (paperwork on an existing building). Default false.
propertySubtypesNoMore-specific building type (2nd level).
constructionTypesNoConstruction type: new_building, addition, renovation, site_work, infrastructure, demolition_only, none, not_stated.
hasCompanyContactNoOnly permits with a company phone or email printed on them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: export-record quota (100,000/month on County/State/National), credit cost of 1 per new or changed permit on API Only and trial, no charge for unchanged permits, 404 from get_permit once a permit leaves Boardwalk, and the get_credit_balance follow-up. It also explains contactWithheld and textContactWithheld semantics, which the readOnly/idempotent annotations cannot convey. The one dent is the claim that "permitIds are not accepted", which conflicts with the schema documenting a permitIds parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the walk semantics before billing and withholding detail, and densely written with almost no filler. The closing paragraphs on contactWithheld and naming parties are output-side boilerplate that sits awkwardly in a sync-tool description, but they carry non-obvious rules rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 43-parameter tool with no output schema, it covers the gaps an agent would otherwise hit: pagination via cursor, cost accounting, why a permit may vanish, and how withheld contact fields appear. The only omission is an explicit statement of the response envelope, which the cursor property already references as meta.nextCursor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains all 43 parameters and the baseline is 3. The description adds real value on the cursor/updatedSince interaction and filter inheritance, but its statement that "sort, offset, and permitIds are not accepted" directly contradicts the permitIds property the schema documents, which could cause an agent to drop a valid parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb-resource-scope statement: permits "new to this account or changed since the last delivery" — a delivery/sync semantic, not a search. That single clause distinguishes it from search_permits without needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the three start modes (cursor resumes, updatedSince starts at a time, neither means a full walk), forbids sending both, forbids sort/offset, and says changing filters starts a new walk. It also names the alternative pattern by stating it accepts "the same filters as search_permits", so the agent knows which tool to pick for a one-shot query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources