liendeadline-mcp

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

Goes well beyond the annotations: names the exact credential required, states that no request is made without it, enumerates the 401/403/429 failure modes, and discloses the billing side effect ('successful calculations consume one API plan unit'), which is consistent with readOnlyHint=false and destructiveHint=false. Null/empty-value semantics and the 'not legal advice' disclaimer round out the behavioral picture.

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?

The credential precondition is front-loaded where it matters most, and the long middle sentence is justified by the absence of an output schema. The enumerated return-field list is dense and could have been tightened, but every clause still carries information.

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 and five parameters, the description fully compensates: it documents the return field set, null and empty-list conventions, error classes, billing cost, and legal disclaimer. An agent can call this correctly and interpret the response without further documentation.

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 all five parameters are already documented with formats and examples. The description reinforces that deadlines count from the invoice or delivery date and that project_type/state drive the result, but adds no syntax or validation detail beyond the schema, so baseline 3 applies.

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 and resource: calculates preliminary notice and lien filing deadlines for one construction invoice, with state and date inputs named. It partially distinguishes itself from the supplier siblings only indirectly, via the 'customer key' requirement, and never names calculate_supplier_deadlines or the state-guide tools as alternatives.

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?

The auth precondition ('requires LIENDEADLINE_API_KEY... without one it returns a configuration error and makes no request') implicitly tells the agent when this tool will work, but there is no explicit when-to-use vs. when-not, and the closely related siblings (calculate_supplier_deadlines, calculate_supplier_deadlines_v3, get_state_lien_guide) are never referenced.

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

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

With annotations declaring write-ish flags (readOnlyHint false, idempotent false, openWorld true), the description adds real operational context: it mutates nothing, requires a customer key, consumes one calculation unit, and performs no API call on invalid input – which explains the non-read-only hints. It also clarifies that review_required is a valid result, not an error.

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?

It is a dense wall of run-on sentences covering conditional rules, return shape, billing, and disclaimers with little front-loading. The key routing fact (deadline calculation) is buried and the structure is hard to parse quickly.

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?

For an 11-parameter tool with no output schema, it covers the return shape (statuses, deadline fields, warnings, citations, echo, disclaimer), auth/billing, and the state-specific conditional rules. Remaining gaps are minor, such as versioning relative to _v3.

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 the schema already documents each parameter and default 3 would be acceptable. The description goes beyond by stating conditional dependencies (last_delivery_date required when deliveries_complete is true; FL/KS-specific fields rejected elsewhere; date accepted only with matching yes), which the schema does not express.

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?

The description states a specific verb (calculates) and resource (supplier preliminary notice and lien filing deadlines) and names the delivery events source. It does not differentiate itself from the sibling calculate_supplier_deadlines_v3, so it falls short of a 5.

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?

It implies usage for deadline-date questions and states coverage limits (FL/KS private only, others return review_required), which is close to when-to-use, but never explicitly says when to choose this over calculate_supplier_deadlines_v3 or the get_* guide tools.

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

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

With annotations declaring readOnlyHint=false, openWorldHint=true and non-idempotency, the description adds real operational context: stale identities return 409, unavailable reviewed sources return 503, a customer key is required, one plan calculation unit is consumed, and no project is saved, notice sent, or lien filed. It does not contradict the non-readOnly hint (credit consumption is a side effect), and it clarifies the safety profile beyond the bare annotations.

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 purpose and outcome, but the body is a dense run-on of overlapping negations ('do not establish filing deadlines', 'do not establish statutory expirations', 'not legal deadlines, service, completion or scheduled reminders') that repeat the same disclaimer across each collection. Much of it earns its place given the missing output schema, but it is not tight.

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?

No output schema exists, so the description must carry return semantics, and it does: it names candidate_deadlines, notice_duties, planned_notice_targets, action_by, Tennessee recurring_notice_periods and NH recurring_notice_checkpoints, explains what each does and does not establish, and covers auth, metering and error codes. For a 7-parameter, nested, high-complexity tool this is complete.

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 description coverage is 71% and the schema itself documents state, events, rules_source, questions_identity and the recurring_notice_facts oneOf in detail. The prose adds meaning for recurring_notice_facts and for how events identities must match discovery, but adds little for the enum/required parameters. Baseline 3 is appropriate.

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 and resource: evaluates discovered supplier-events-v3 facts against rule/question identities and returns independent notice and lien outcomes. Clear enough that an agent knows what it produces, but it never distinguishes itself from the sibling calculate_supplier_deadlines (presumably the older version), so version selection is left to inference.

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 conditional reasoning guidance (e.g. 'When RI discovery asks ri_mailed_within_200_days...') and gates recurring_notice_facts ('Only when discovery returns a matching recurring_notice_intake descriptor'), but never says when an agent should call this tool versus calculate_supplier_deadlines or get_supplier_questions. Usage is implied by the workflow, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context: the response is roughly 4 KB of JSON, an unknown state code produces an error, and the day counts are editorial summaries rather than computed deadlines — an important trust caveat not conveyed by any structured field.

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?

The paragraph is front-loaded with the return shape, then usage conditions, then error behavior, then the editorial disclaimer, then auth. Every sentence carries distinct information (payload fields, use cases, error case, trust caveat, access model) with no filler.

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 takes on the burden of describing the return shape, and it does so explicitly (rules, deadline_rows, faqs, source_url, ~4 KB). Combined with annotations covering safety and the description covering error behavior and the editorial disclaimer, an agent has everything needed to call and interpret this correctly.

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 the two-letter code format, case-insensitivity and example are already documented, which sets the baseline at 3. The description adds value beyond the schema by specifying the error behavior for an unrecognized state code, giving the agent validation semantics the schema does not encode.

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?

The description opens with a specific verb and resource: it returns LienDeadline's editorial mechanics lien and preliminary notice guide for one state or DC, and enumerates the exact payload (rules, deadline_rows, faqs, source_url). It implicitly distinguishes itself from the calculation sibling by framing the output as editorial reference material rather than computed deadlines.

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?

It states clear when-to-use conditions ('For questions about how a state's lien or notice rules work, why a deadline falls where it does, or which statute applies') and notes the failure mode for an unknown state code. It does not explicitly name calculate_supplier_deadlines or list_state_lien_guides as alternatives, so the routing signal is implied rather than spelled out.

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

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

Goes well beyond the annotations (readOnly/idempotent/openWorld) by disclosing that a customer key is required, that discovery consumes no calculation quota, that a 503 signals an unavailable reviewed source, and that approving research alone does not activate a scope. These are operationally important behaviors an agent cannot infer from the structured fields.

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-loads what is returned before the operational caveats, and every sentence carries information. The phrasing is dense and clause-heavy, but nothing is redundant.

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 appropriately enumerates the returned fields (scope support, questions, date policies, recurring_notice_intake descriptor, sources/identities) and covers the auth requirement and a failure mode. Parameter semantics remain thin, which is the only real completeness gap.

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 only 33%: hired_by and project_type are enums with no descriptions, and only 'state' is documented. The description's 'jurisdiction-specific' and 'material supplier' hints loosely touch state and persona but leave hired_by's meaning and the commercial/residential/public distinction unexplained, so it does not compensate for the coverage gap.

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+resource: returns supplier-events-v3 scope support, jurisdiction-specific yes/no/unknown event questions, date policies, and rule identities for a material supplier. The scope is narrow enough that an agent can separate it from calculate_supplier_deadlines without opening either 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?

Indicates the discovery use case clearly ('no delivery dates needed', 'does not consume calculation quota'), which steers toward this tool over the calculate_* siblings. It stops short of explicitly naming an alternative or stating a when-not-to-use condition.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), but the description adds real value beyond them: no pagination, alphabetical ordering, inclusion of a count, editorial-only scope, and explicit 'public; no key needed' auth disclosure. It does not cover failure modes, which keeps it short of a 5.

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 core action and scope, and every sentence carries information (ordering, count, exclusions, auth). Minor overlap between 'Public and read-only' and the readOnlyHint annotation is the only redundancy.

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 correctly compensates by enumerating the return shape (count plus state_code, title, slug) and the ordering. For a zero-parameter read tool this is complete enough to call blind.

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, so the baseline is 4. The description correctly states 'Takes no parameters', which matches the empty schema and prevents the agent from hunting for filters.

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 (every published state lien guide) with explicit scope: all 50 states and DC, in one response, no pagination. The plural 'every ... guide' plus the returned fields distinguishes it from the singular sibling get_state_lien_guide 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.

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

Usage is implied rather than stated: 'does not indicate which states have calculated deadlines' hints that calculate_supplier_deadlines is the tool for deadline data, but no sibling is named and no explicit when-to-use/when-not rule is given. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavior: the LIENDEADLINE_API_KEY requirement and the states:read scope, plus the return shape (count + codes), which the annotations cannot convey.

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?

Four short sentences, front-loaded with the auth requirement and return content, then exclusions, then no-params. Efficient overall, though 'Read-only' is mild redundancy against the readOnlyHint annotation.

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 describing the return (count and two-letter codes), the auth prerequisite, and the exclusions. Nothing an agent needs to call this zero-parameter read tool 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?

The tool takes zero parameters, so there is nothing to document; the description correctly states 'Takes no parameters.' Baseline 4 applies since no param semantics are needed.

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 and resource: returns the count and two-letter codes of jurisdictions the customer invoice calculation accepts. It actively distinguishes itself from the sibling list_state_lien_guides by stating it does not list editorial guides or reviewed-baseline states, so an agent can tell them apart without opening schemas.

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?

Frames usage by identifying the audience/tool family ('Customer API tool') and the required key/scope, and rules out the guide-oriented sibling use case. It stops short of naming the alternative tool explicitly, so the guidance is clear but not fully prescriptive.

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