US mechanics lien and preliminary notice deadlines for construction suppliers, with statute sources.
Scored across 3 tools
Each tool has a clearly distinct role: calculate_supplier_deadlines computes dates, get_state_lien_guide returns editorial rule content for one state, and list_state_lien_guides enumerates valid guide codes. The descriptions explicitly instruct when to use each, including calling list before get, so an agent can easily tell them apart.
All three tools follow a consistent verb_noun snake_case pattern: calculate_supplier_deadlines, get_state_lien_guide, list_state_lien_guides. The naming is predictable and directly reflects each tool's action and target resource.
Three tools are well-scoped for a focused lien-deadline calculator and reference guide. Each tool earns its place: one calculates, one retrieves a single guide, and one lists available guides without pagination.
The surface covers the core workflow: discover states, read rules, and calculate deadlines for supported baselines. A minor gap is the lack of a direct tool to list which states have calculation support (vs. editorial guides), though calculate_supplier_deadlines indicates unsupported states via review_required.
Calculates a construction material supplier's preliminary notice and lien filing deadlines from delivery events (contract supplier-events-v2). Use it whenever the user needs dates; use get_state_lien_guide to explain the rules behind them. Reviewed baselines cover Florida and Kansas private projects; other states and public projects return review_required, which is an answer, not an error. How the parameters depend on each other: last_delivery_date is required when deliveries_complete is true. Florida (FL) asks florida_final_payment_status and florida_termination_status; Kansas (KS) asks kansas_extension_status; these are rejected for other states. Answer each yes, no or unknown: an omitted or unknown answer keeps the affected deadline under review, and a blanket review flag is not accepted. A Florida event date is accepted only with the matching yes answer. Ask the user for missing facts instead of guessing, and never use an invoice date as a delivery date. Returns JSON with an overall status (calculated or review_required), preliminary_notice and lien_filing (each with its own status: calculated, not_required, review_required or awaiting_final_delivery, plus deadline, days_from_now, description and statute source_url), critical_warnings, statute_citations, an exact echo of the submitted inputs and a disclaimer. Invalid or contradictory facts return an error naming the field before any API call. Public, stateless and read-only: no key needed, nothing is stored, and no notice is sent or lien filed. Not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | Two-letter code of the state where the project is located, e.g. "FL", "KS", "TX"; any state or DC is accepted. Decides which event questions apply. | |
| hired_by | Yes | Who ordered the materials from the supplier: the owner, a contractor or a subcontractor. | |
| project_type | Yes | Private commercial, private residential, or public (public projects always need review). | |
| last_delivery_date | No | Date of the final delivery, YYYY-MM-DD, not earlier than first_delivery_date. Required when deliveries_complete is true. | |
| deliveries_complete | Yes | true when the final delivery has happened (then last_delivery_date is required); false while deliveries are ongoing, which returns awaiting_final_delivery for the lien date. | |
| first_delivery_date | Yes | Date materials were first delivered (first furnishing), YYYY-MM-DD. Not an invoice date. | |
| kansas_extension_status | No | Kansas only: was a statutory lien-period extension filed and mailed? no permits the ordinary lien baseline; yes, unknown or omitted requires qualified review. | |
| florida_termination_date | No | Florida only: contract or notice-of-commencement termination date, YYYY-MM-DD, not earlier than first_delivery_date. Supply only with florida_termination_status=yes; a lien date still requires qualified review. | |
| florida_final_payment_date | No | Florida only: owner final-payment date, YYYY-MM-DD, not earlier than first_delivery_date. Supply only with florida_final_payment_status=yes. | |
| florida_termination_status | No | Florida only: was the original contract or notice of commencement terminated? no permits the lien baseline; yes, unknown or omitted requires qualified lien review. | |
| florida_final_payment_status | No | Florida only: did the owner make final payment to the contractor? Use unknown if unverified; omitted or unknown keeps the notice under review, and yes needs florida_final_payment_date for a notice baseline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: stateless with no key required, nothing stored, no notice sent or lien filed, review_required semantics for uncovered states, 'blanket review flag is not accepted', and pre-flight validation that errors name the field before any API call. This is well beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and the sibling routing rule, and every sentence carries content. It is dense and long for a single paragraph, and a few parameter-dependency sentences duplicate schema descriptions, but there is little pure padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by describing the return JSON in detail (overall status, per-deadline statuses, critical_warnings, statute_citations, echoed inputs, disclaimer). For an 11-parameter, state-conditional tool, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so per-field meanings are already documented, but the description adds cross-parameter dependencies the schema states only in isolation: last_delivery_date required when deliveries_complete is true, which states accept which conditional questions, that FL/KS-only params are rejected for other states, and a Florida event date being accepted only with the matching 'yes' answer. It stops short of restating individual field formats, which the schema already handles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('Calculates a construction material supplier's preliminary notice and lien filing deadlines') and scopes the input to delivery events. It explicitly distinguishes itself from the sibling get_state_lien_guide, so an agent can tell the two apart without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit routing rule: 'Use it whenever the user needs dates; use get_state_lien_guide to explain the rules behind them.' It also sets expectations for unsupported jurisdictions ('other states and public projects return review_required, which is an answer, not an error') and instructs the agent to ask for missing facts rather than guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns LienDeadline's editorial mechanics lien and preliminary notice guide for one state or DC: rules (rule summary with statute citations), deadline_rows (deadline table), faqs (common questions) and source_url (the guide's web page), roughly 4 KB of JSON. Use it when the user asks how a state's lien or notice rules work, why a deadline falls where it does, or which statute applies. Call list_state_lien_guides first if you need the valid codes; an unknown code returns an error. Editorial reference, not a calculation. Do not derive filing dates from the day counts; use calculate_supplier_deadlines, and treat anything it does not calculate as requiring qualified review. Public and read-only; no key needed.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | Two-letter US state or DC code, e.g. "TX"; case-insensitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on behavior beyond them: response size (~4 KB JSON), error semantics for unknown codes, no-key public access, and the crucial caveat that it is editorial reference rather than a calculation engine.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what it returns before the routing guidance and caveats, and every clause carries real information. It is dense with several distinct ideas packed into one paragraph, which costs a bit of scannability but wastes nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still enumerates the returned fields and their rough size, states error behavior, disclaims calculation duty, and notes public read-only access. Nothing an agent needs to select or invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single param is fully documented there, so the baseline is 3; the description adds value by pointing the agent at list_state_lien_guides as the source of valid codes and warning that unknown codes error out, which clarifies valid-value discovery beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (returns) and resource (editorial mechanics lien and preliminary notice guide for one state or DC), then enumerates the payload fields (rules, deadline_rows, faqs, source_url). An agent can distinguish it from calculate_supplier_deadlines and list_state_lien_guides without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use triggers ('user asks how a state's lien or notice rules work, why a deadline falls where it does, or which statute applies'), a named prerequisite (call list_state_lien_guides first for codes), and a named alternative with an explicit exclusion ('Do not derive filing dates from the day counts; use calculate_supplier_deadlines').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every published state lien guide in one response, without pagination: count plus state_code, title and slug for all 50 states and DC, in alphabetical order by state name. Use it to find a valid code before calling get_state_lien_guide. It lists editorial guides only, not where calculate_supplier_deadlines produces dates. Takes no parameters. Public and read-only; no key needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: single unpaginated response, exact fields returned, alphabetical ordering, and that no API key is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: the scoping constraint and return shape come first, routing guidance second, auth note last. Every clause carries information, though the ordering detail is close to surplus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields and shape (count plus state_code/title/slug). For a simple read-only list tool, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, and the description confirms 'Takes no parameters,' so there is nothing to clarify. Baseline 4 applies for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (lists) and resource (state lien guides) with explicit scope: all 50 states and DC, editorial guides only, no pagination. It also names both siblings and distinguishes itself from each, so the agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use rule ('find a valid code before calling get_state_lien_guide') and an explicit when-not-to-use boundary versus calculate_supplier_deadlines. Alternatives are named with the condition that selects them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
calculate_supplier_deadlinesget_state_lien_guidelist_state_lien_guidesUS LLC filing fees, deadlines, and name checks for all 50 states — from official sources.
Fresh US building permits with contacts from official city APIs. Construction lead generation.
Source-linked building-permit search across 34 US states and DC, with county-level coverage.
US pre-construction land-use filings, alerts, lists, and exports.
Add one secure layer between your agents and this server.
