Skip to main content
Glama

Count matching building permits

count_permits
Read-onlyIdempotent

How many building permits match a filter set, and what fetching them would use. Same filters as search_permits: q (permit text or number), contractor, Region, Work type, Status, Why now, Value, Date, Building type, Trades, and contact switches. Returns matchCount and the export-record or credit quote. Returns no permit records. The default is major and minor jobs with activity in the last 12 months; dateRange="all" counts every date. permitIds (at most 100) re-prices permits already in hand and must be the only filter. A place outside permit coverage is not covered yet, which is different from having no permits; get_permit_reference with facet="coverage" lists coverage. Does not use credits.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "count_permits"
  }
}

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.
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.
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.
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.5/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/closed-world, and the description adds genuinely new behavior: the default scope (major+minor jobs with activity in the last 12 months), dateRange="all" to widen it, the 100-id cap, and the fact it "Does not use credits" while still returning a credit or export quote. That credit disclosure materially changes how an agent plans a call.

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 answer and the negative scope, then defaults, then the permitIds special case, then the coverage caveat — a sensible order. A few clauses are dense and could be trimmed, but no sentence is filler.

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

Completeness4/5

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

For a 40-parameter aggregator with no output schema, it covers what is returned (matchCount plus export-record or credit quote), the default filtering, and the main edge case (coverage vs. zero results). What "export-record or credit quote" concretely contains is left vague without an output schema to lean on.

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

Parameters4/5

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

Schema coverage is 100% across 40 parameters, so the baseline is 3; the description adds value by condensing the filter families (Region, Work type, Status, Why now, Value, Date, Trades, contact switches) into one readable sentence and by stating the permitIds-only constraint and default window that the schema itself doesn't state as rules.

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 specific verb+resource question ("How many building permits match a filter set") and immediately bounds the output ("Returns no permit records"), which separates it from search_permits/analyze_permits without opening a schema. It also names the sibling whose filter vocabulary it shares.

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

Usage Guidelines4/5

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

Gives clear context: counting, not record retrieval, with permitIds as a re-pricing path that "must be the only filter". It points to get_permit_reference facet="coverage" for out-of-coverage places. It stops short of explicitly saying "use search_permits instead when you need the permit records", leaving that to inference.

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