H3: Schema-Intent Mismatch #

The schema and selection contract disagree or leave inputs underspecified.

Applies to: Recognized tool input schemas; narrower generic-property checks for extracted standalone/response schemas. Manual repair; no automatic fix for this example.

What triggers it #

Tool-schema checks cover phantom required fields, underspecified parameters, generic names, selected structural unions, and nested objects. Other recognized schemas receive a narrower check for generic property names without a description field. It is not full JSON Schema validation.

How to repair it #

Make required names match properties, explain ambiguous parameters and structural variants, and describe nested objects.

Reproduce the finding #

Use uv and Python 3.10+, plus curl. Run the examples in a scratch directory.

Download the finding example.

{
  "tools": [
    {
      "name": "lookup_invoice",
      "description": "Retrieve an invoice by its invoice ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "invoice_id": {
            "type": "string",
            "description": "The invoice identifier from the billing system."
          }
        },
        "required": [
          "invoice_key"
        ]
      }
    }
  ]
}

curl -fsS https://lintlang.ai/examples/rules/h3-bad.json -o h3-bad.json
uvx --from lintlang==0.8.0 lintlang scan h3-bad.json --format json

Expected with 0.8.0: the JSON report includes H3, severity HIGH. This example corrects a required field name while preserving the intended invoice identifier. Other H3 diagnostics use the same family code.

Improved example #

Download the improved example.

{
  "tools": [
    {
      "name": "lookup_invoice",
      "description": "Retrieve an invoice by its invoice ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "invoice_id": {
            "type": "string",
            "description": "The invoice identifier from the billing system."
          }
        },
        "required": [
          "invoice_id"
        ]
      }
    }
  ]
}

curl -fsS https://lintlang.ai/examples/rules/h3-improved.json -o h3-improved.json
uvx --from lintlang==0.8.0 lintlang scan h3-improved.json --format json

Expected with 0.8.0: H3 is absent. Other diagnostics may still appear; this repair targets the rule above.

Both commands use advisory mode: a finding does not itself make the command fail. To fail CI on HIGH or CRITICAL findings, add --fail-on fail. --fail-on review also gates MEDIUM. See outputs and exit codes.

Detection details #

All scan rules · Quickstart · Separate preflight checks.