liendeadline-mcp

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial value: the dedicated LIENDEADLINE_API_KEY requirement and its fail-fast behavior, the 401/403/429 error surface, and how absent fields are represented (null for dates/counts, [] for warnings, empty string for notes). That goes well beyond what the structured fields 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?

Leads with the auth prerequisite, then purpose, then the return contract – a sensible front-loaded order with no filler. It is on the long side because the field-by-field return enumeration and null/empty conventions take several clauses, though the absence of an output schema partly justifies that.

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 carries the return contract itself: field names, null/empty conventions, warning behavior, and the four error responses. Combined with the auth prerequisite and the 'not legal advice' caveat, 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 description coverage is 100%, so every parameter is already documented in the schema, including formats and examples. The description only restates that deadlines derive from invoice/delivery date and state, adding no syntax or edge-case detail beyond the schema – the baseline 3 for high coverage.

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 concrete verb and resource: calculates preliminary notice and lien filing deadlines for one construction invoice from invoice/delivery date and state. The 'Customer API tool' framing hints at a distinction from the supplier siblings, but it never names an alternative, so the agent gets clear purpose without explicit sibling differentiation.

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 description says nothing about when to pick this tool over calculate_supplier_deadlines or calculate_supplier_deadlines_v3, nor what preconditions or jurisdiction limits apply. The only routing signal is the API-key requirement, which is a credential constraint rather than usage guidance.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), the description discloses that the tool is public, stateless and read-only, needs no key, stores nothing, and sends no notice or files no lien. It also explains the failure mode ('invalid or contradictory facts return an error naming the field before any API call') and that review_required is intentional output, 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?

Purpose and supported scope are front-loaded, then dependency rules, then return shape, then safety posture — a logical order with no filler sentences. It is dense and re-states a few facts already in the schema (state codes, hired_by), which slightly dilutes conciseness.

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, and the description fully compensates by enumerating the returned structure: overall status (calculated or review_required), preliminary_notice and lien_filing each with their own status values, deadline, days_from_now, description, statute source_url, plus critical_warnings, statute_citations, an input echo and a disclaimer. For an 11-parameter tool with complex conditional rules, nothing essential to correct invocation appears to be 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?

Although schema coverage is already 100%, the description adds cross-parameter semantics the schema cannot express: last_delivery_date is required when deliveries_complete is true, FL parameters are rejected for other states, each yes/no/unknown answer governs whether a deadline stays under review, and a blanket review flag is not accepted. It also clarifies that a Florida event date is only valid with the matching 'yes' answer and that delivery dates are furnishing, not invoice, dates.

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 precise verb+resource+scope: calculating a construction material supplier's preliminary notice and lien filing deadlines from delivery events. An agent immediately knows the domain and output. However, it never distinguishes itself from the sibling calculate_supplier_deadlines_v3, so the reader cannot tell which of the two near-identical tools to pick.

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 the triggering condition ('for questions that need deadline dates'), names the supported baselines (Florida and Kansas private projects), and pre-empts a misread by explaining that review_required for other states/public projects is a valid result rather than an error. It stops short of naming alternatives such as get_state_lien_guide or the v3 sibling, so it is clear context without explicit routing.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds real value beyond that: 409 on stale identities, 503 on unavailable reviewed sources, 'stateless and public; no key, stored records, sent notices or filed liens', plus the note that only calculated outcomes carry deadline dates while review candidates stay unresolved.

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?

Five tight sentences, front-loaded with the core action, then return semantics, then error behavior, then the safety/hosting profile. No filler, though the error-code sentence is listy and could be folded slightly tighter.

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-value burden, and it does: independent notice and lien outcomes, sources, an exact nested input echo, and the calculated-vs-review distinction. Combined with the error codes, an agent has enough to call and interpret it, though the meaning of 'review candidates' is left implicit.

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 67% and the nested objects (events, rules_source, questions_identity) are largely documented in the schema itself. The description adds behavioral meaning to the identity params ('exact discovered' values, stale ones 409) and clarifies the output rule for events, but contributes little on syntax or format beyond what the schema provides. Baseline 3 fits.

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 supplier-events-v3 project facts against discovered rules and question identities to produce notice and lien outcomes. Clear about what it does, but it never distinguishes itself from the sibling calculate_supplier_deadlines (the non-v3 variant), so an agent cannot tell from the text which calculator to pick.

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 only implied: the repeated emphasis on 'discovered' rule and question identities signals this must run after a discovery step (get_supplier_questions / get_state_lien_guide), but no explicit when-to-use, when-not, or sibling comparison is given. The workflow ordering is inferable but 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?

Annotations already declare read-only, idempotent, non-destructive, so the description doesn't need to restate safety. It does add real behavioral context: no key or delivery dates needed, a 503 signals an unavailable reviewed source, and the scope-activation caveat is a genuine workflow warning. That is useful beyond 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?

Two long, densely packed sentences front-load a broad list of outputs before stating the actual input-framed purpose. Nothing is egregiously wasteful, but the ordering buries the actionable part and the enumerated output list is hard to parse.

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 must convey return shape, and it lists categories (scope support, event questions, date policies, sources, rule identities) which partially does that. But it omits error handling beyond the 503 hint, pagination/format, and how the three required parameters change the response, so it's only minimally complete for a discovery endpoint.

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%, so the description should compensate, but it doesn't explain how state, hired_by and project_type shape the returned questions. The two enums are self-documenting, but hired_by's semantics (whose perspective drives the question set) are left entirely to 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?

The description names the resource ('supplier-events-v3 scope', 'jurisdiction-specific event questions', 'date policies', 'sources') but is dense and jargon-heavy, mixing several outputs into one clause. The verb 'Returns' is generic, and it never cleanly states it's a discovery/lookup endpoint for a given state, project type and hiring role. An agent knows roughly what comes back, but the purpose is blurred.

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?

No when-to-use or when-not-to-use guidance is given, and none of the siblings are named or contrasted. The line 'Approval of research alone does not activate a scope' hints at a workflow caveat but doesn't tell the agent when to call this tool versus the deadline calculators or lien guides.

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.