Plumbline - Contractor License Checks

Check a contractor's license record

check_contractor

Read-onlyIdempotent

Looks up a contractor's public credential in indexed state and local licensing records. Licenses, registrations and bond records mean different things. Each record carries a credential object (kind, label, note): kind is license, registration, business_license or bond when the source makes that clear; otherwise it is the generic "credential", and the note says what to verify with the issuing agency. The set of covered jurisdictions changes as sources are added, so this description does not list it. Inputs: a record number (license) or business name, with optional jurisdiction and exact listed city, or an entity_id from an earlier result, which selects that one record. Results: match (the credential record with its status and provenance); candidates (several records fit; each page holds up to 20 rows, total_candidates is the full count, offset pages through the rest, and entity_id selects one; a field with the same value on every row of a page is given once, in same_for_all_rows, and each row's entity block omits what the row already states); no_match_in_index (the index holds no record for that input, which does not mean the contractor is unlicensed; for a search across all jurisdictions, the message states how many covered jurisdictions were searched); or jurisdiction_not_covered (the requested jurisdiction is outside the index, with an official pointer URL where one is on file; the response message states exactly what the link is, or that none is on file, and for some jurisdictions the link is a consumer-protection or licensing-board page, not a license lookup).

Input Schema

TableJSON Schema

Name	Required	Description
`city`	No	Optional exact record-city filter, case-insensitive. Filters before pagination; does not represent service area or silently drop terms.
`name`	No	Business name, e.g. "Bayside Plumbing"
`offset`	No	Pagination offset into the candidates list, a whole number, default 0. Each page holds up to 20 candidates; total_candidates in a candidates result is the full count. An offset past the end returns an empty candidates list with a message saying so; a negative or fractional offset returns an error.
`license`	No	License number, e.g. "1000002"
`entity_id`	No	The exact entity.id from a previous response. It selects that one record, keeping records that share a number distinct, and overrides name and license. An id no record carries, or a jurisdiction or city that is not the record's own, returns an error that names the problem.
`jurisdiction`	No	State or local jurisdiction: a state code ("CA" or "US-CA", any case), a full state name ("California", "District of Columbia"), or a local code such as "NYC". Coverage spans dozens of US jurisdictions; a recognized place outside coverage returns jurisdiction_not_covered, and text that names no US state or local code returns an error listing the accepted forms.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 28, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / entity_id / description

Previous value: -"Select the exact entity.id from a previous response, preserving same-number record distinctions. Overrides name/license; supplied jurisdiction and city still constrain selection."New value: +"The exact entity.id from a previous response. It selects that one record, keeping records that share a number distinct, and overrides name and license. An id no record carries, or a jurisdiction or city that is not the record's own, returns an error that names the problem."

changedInput schema / properties / jurisdiction / description

Previous value: -"State or local jurisdiction code, e.g. \"CA\" (\"US-CA\" style also accepted) or \"NYC\". Coverage spans dozens of US jurisdictions; GET /v1/coverage for the exact current list."New value: +"State or local jurisdiction: a state code (\"CA\" or \"US-CA\", any case), a full state name (\"California\", \"District of Columbia\"), or a local code such as \"NYC\". Coverage spans dozens of US jurisdictions; a recognized place outside coverage returns jurisdiction_not_covered, and text that names no US state or local code returns an error listing the accepted forms."

changedInput schema / properties / offset / description

Previous value: -"Pagination offset into the candidates list, default 0. Use with total_candidates from a prior call to page through large candidate sets."New value: +"Pagination offset into the candidates list, a whole number, default 0. Each page holds up to 20 candidates; total_candidates in a candidates result is the full count. An offset past the end returns an empty candidates list with a message saying so; a negative or fractional offset returns an error."

Changed2 schema fields changedSep 27, 2026

addedInput schema / properties / city

Added value: +{
+  "description": "Optional exact record-city filter, case-insensitive. Filters before pagination; does not represent service area or silently drop terms.",
+  "type": "string"
+}

addedInput schema / properties / entity_id

Added value: +{
+  "description": "Select the exact entity.id from a previous response, preserving same-number record distinctions. Overrides name/license; supplied jurisdiction and city still constrain selection.",
+  "type": "string"
+}

First observedAug 5, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/closed-world annotations, the description discloses substantive behavior: coverage changes as sources are added, no_match_in_index does not imply the contractor is unlicensed, jurisdiction_not_covered returns an official pointer that may be a consumer-protection page rather than a lookup, and page-level dedup via same_for_all_rows. This is exactly the extra context annotations cannot carry.

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?

The purpose is front-loaded and every clause carries information, but the result-type enumeration is delivered as a single dense run-on sentence with nested parentheticals. Given there is no output schema, that content earns its place; the structure could still be broken up for scanability.

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 six-parameter tool with no output schema fallback, the description fully covers the return shapes (match, candidates with 20-row paging and total_candidates, no_match_in_index, jurisdiction_not_covered) and the offset/entity_id mechanics. Nothing an agent needs to call or interpret the result is missing.

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% and the schema already documents each parameter in depth, including entity_id overriding name/license and negative-offset errors. The description's input sentence largely restates that structure without adding new syntax or format detail, so the baseline 3 applies.

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?

States a specific verb and resource ('Looks up a contractor's public credential in indexed state and local licensing records') and immediately scopes what those records are. With no sibling tools, no differentiation is needed, and the credential-kind explanation makes the object of the lookup unambiguous.

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?

Specifies how to enter (license number, business name plus optional jurisdiction/city, or a prior entity_id) and what each result class means in practice. It gives clear context for use but no explicit when-not-to-use guidance, which matters less here because no alternative tool exists.

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

All Plumbline - Contractor License Checks tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?