Skip to main content
Glama

Calculate supplier deadlines from confirmed project facts

calculate_supplier_deadlines_v3

Evaluates confirmed supplier-events-v3 facts against the rule and question identities from v3 discovery. Returns separate sourced notice and lien outcomes, including qualified review when relevant facts are unresolved, and an exact nested input echo. When RI discovery asks ri_mailed_within_200_days after ri_mailed=yes, confirm whether mailing occurred within 200 days of first delivery. No, Unknown or omitted confirmation requires review; recording alone does not establish a 40-day target. Only calculated outcomes contain calculated deadline dates. Report every candidate_deadlines entry with its ID, date and sources under the API explanation. For NH review fallbacks, first_furnishing is a conservative checkpoint and final_furnishing is informational pending contract grouping and qualifying completion; passing the first checkpoint does not itself establish expiry. A calculated contract_completion outcome uses only the returned deadline, without substituting the first checkpoint or recomputing a date. Review candidates do not establish filing deadlines, completion or scheduled reminders. An optional preliminary_notice.notice_duties collection contains independently required named notices, each with its own calculated date, explanation and sources; the legacy preliminary date is only their earliest summary. Report every validated duty without inferring duties from candidates or treating one notice as satisfying all duties. A separate optional preliminary_notice.planned_notice_targets collection contains qualified intent planning targets with their target dates, assumed filing dates, full ten- or thirty-day intervals, explanations and sources. Planning targets do not establish statutory expirations, actual filing, notice completion or scheduled notifications. An optional verified action_by is a Conservative action date planning target under qualified review; the statutory deadline and countdown remain unresolved, with explanation, sources and warnings. Optional recurring_notice_facts supplies actual Tennessee furnished months or New Hampshire account records. Tennessee recurring_notice_periods cover entered periods only, including paid and unknown states; known unpaid duties remain independent. New Hampshire recurring_notice_checkpoints are advisory check-ins with unresolved legal status, not legal deadlines, service, completion or scheduled reminders; they do not reset earlier gaps. Never infer intervening months or blanket completion. Stale identities return 409, unavailable reviewed sources return 503. Requires a customer key and consumes one plan calculation unit. No project is saved, notice sent or lien filed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "state": "<state>",
      "project_type": "<project_type>",
      "hired_by": "<hired_by>",
      "rules_source": "<rules_source>",
      "questions_identity": "<questions_identity>",
      "events": "<events>",
      "context": "<context>"
    },
    "name": "calculate_supplier_deadlines_v3"
  }
}

Input Schema

NameRequiredDescriptionDefault
stateYesProject jurisdiction: state or DC.
eventsYesDiscovered event IDs only; missing means unknown. Date only for yes and only where the question permits it. Invoice dates are not furnishing dates.
contextYesFor anonymous analytics, use one of these exact goals. Determine supplier notice and lien deadlines / Identify which facts a supplier calculation needs / Read a state's lien guide / Browse available lien guides. Leave empty if none fits. Keep personal and project information out of this field.
hired_byYesWho ordered the materials from the supplier: the owner, a contractor, or a subcontractor.
project_typeYesConstruction project type: private commercial, private residential, or public.
rules_sourceYesExact rules_source from discovery for this scope.
questions_identityYesExact questions_identity from discovery.
recurring_notice_factsNoOnly when discovery returns a matching recurring_notice_intake descriptor. Actual recurring facts only: Tennessee entered furnished months with unpaid and retainage-only answers, or New Hampshire actual written accounts with coverage and supplied dates. Omission retains legacy behavior; unknown answers require review. Do not infer intervening months or actual notice from a plan. NH actual owner notice belongs in the discovered nh_owner_notice_given event.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  2. Changed2 schema fields changed
    • addedInput schema / properties / hired_by / description
      Added value: +"Who ordered the materials from the supplier: the owner, a contractor, or a subcontractor."
    • addedInput schema / properties / project_type / description
      Added value: +"Construction project type: private commercial, private residential, or public."
  3. Changed2 schema fields changed
    • addedInput schema / properties / context
      Added value: +{
      +  "description": "For anonymous analytics, use one of these exact goals. Determine supplier notice and lien deadlines / Identify which facts a supplier calculation needs / Read a state's lien guide / Browse available lien guides. Leave empty if none fits. Keep personal and project information out of this field.",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "state",
      -  "project_type",
      -  "hired_by",
      -  "rules_source",
      -  "questions_identity",
      -  "events"
      -]New value: +[
      +  "state",
      +  "project_type",
      +  "hired_by",
      +  "rules_source",
      +  "questions_identity",
      +  "events",
      +  "context"
      +]
  4. Changed1 schema field changed
    • addedInput schema / properties / recurring_notice_facts
      Added value: +{
      +  "description": "Only when discovery returns a matching recurring_notice_intake descriptor. Actual recurring facts only: Tennessee entered furnished months with unpaid and retainage-only answers, or New Hampshire actual written accounts with coverage and supplied dates. Omission retains legacy behavior; unknown answers require review. Do not infer intervening months or actual notice from a plan. NH actual owner notice belongs in the discovered nh_owner_notice_given event.",
      +  "oneOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "kind": {
      +          "const": "tn_monthly_nonpayment",
      +          "type": "string"
      +        },
      +        "months": {
      +          "items": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "month": {
      +                "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
      +                "type": "string"
      +              },
      +              "retainage_only": {
      +                "enum": [
      +                  "yes",
      +                  "no",
      +                  "unknown"
      +                ],
      +                "type": "string"
      +              },
      +              "unpaid": {
      +                "enum": [
      +                  "yes",
      +                  "no",
      +                  "unknown"
      +                ],
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "month",
      +              "unpaid",
      +              "retainage_only"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 16,
      +          "minItems": 1,
      +          "type": "array"
      +        },
      +        "version": {
      +          "const": "supplier-recurring-facts-v1",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "version",
      +        "kind",
      +        "months"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "accounts": {
      +          "items": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "covered_through": {
      +                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +                "type": "string"
      +              },
      +              "id": {
      +                "pattern": "^[a-z][a-z0-9_]{0,79}$",
      +                "type": "string"
      +              },
      +              "supplied_date": {
      +                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "id",
      +              "covered_through",
      +              "supplied_date"
      +            ],
      +            "type": "object"
      +          },
      +          "maxItems": 16,
      +          "type": "array"
      +        },
      +        "kind": {
      +          "const": "nh_written_account",
      +          "type": "string"
      +        },
      +        "version": {
      +          "const": "supplier-recurring-facts-v1",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "version",
      +        "kind",
      +        "accounts"
      +      ],
      +      "type": "object"
      +    }
      +  ]
      +}
  5. Added

TDQS

A3.6/5.0
Behavior4/5

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

With annotations declaring readOnlyHint=false and openWorldHint=true, the description resolves the obvious ambiguity: no project is saved, no notice is sent, no lien is filed, and only a customer key and one plan calculation unit are consumed. That is exactly the kind of context annotations cannot convey. It loses a point because it never explains idempotency or what a repeated call with identical inputs does, despite idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, which is good, but the remainder is a single unstructured block of run-on clauses mixing return-value semantics, review fallbacks, planning targets, error codes, billing and side effects. Sentences such as the qualified-review and first_furnishing passages require re-reading to parse. Much of the volume is genuine caveat content, but it is delivered without headings, lists or grouping, so the reader cannot route through it efficiently.

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 nested-schema, seven-required-parameter computation with no output schema, the description does substantial work explaining the return surface: calculated outcomes versus review candidates, candidate_deadlines with IDs and sources, the independent preliminary_notice.notice_duties collection, planned_notice_targets, verified action_by and recurring checkpoints. It also states the distinction that only calculated outcomes contain calculated deadline dates, which is critical for downstream use. What is missing is the concrete shape or ordering of the response, though naming Output schema absence makes this a smaller gap.

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 description coverage is 100%, so the schema already carries baseline documentation for all eight parameters. The description still adds real meaning the schema lacks, notably the ri_mailed/ri_mailed_within_200_days pairing and the warning that recording alone does not establish a 40-day target. It also frames recurring_notice_facts as actual Tennessee furnished months versus New Hampshire account records, which the schema only names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a concrete verb and resource: it evaluates confirmed supplier-events-v3 facts against v3 discovery rule and question identities and returns sourced notice and lien outcomes. That is far more specific than a restated name. It never mentions the sibling calculate_supplier_deadlines, so the agent gets no explicit signal about why the v3 variant should be chosen over it.

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

Usage Guidelines3/5

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

There is rich conditional guidance for specific inputs, e.g. when RI discovery asks ri_mailed_within_200_days after ri_mailed=yes the agent must confirm whether mailing occurred within 200 days of first delivery, and that No/Unknown/omitted requires review. It also states 409 for stale identities and 503 for unavailable reviewed sources. However, guidance is entirely about interpreting inputs and outcomes rather than about when to prefer this tool over alternatives, and the constraints are scattered rather than stated as use criteria.

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.