# H3: Schema-Intent Mismatch

The schema and selection contract disagree or leave inputs underspecified.

<div class="rule-facts"><span>H3</span><span>LOW–HIGH</span><span>LintLang 0.8.0</span></div>

**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+](/docs/install), plus curl. Run the examples in a scratch directory.

[Download the finding example](/examples/rules/h3-bad.json).

```json
{
  "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"
        ]
      }
    }
  ]
}
```

```sh
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](/examples/rules/h3-improved.json).

```json
{
  "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"
        ]
      }
    }
  ]
}
```

```sh
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](/docs/outputs).

## Detection details

<details>
<summary>Released H3 detection contract and scope</summary>

Checks phantom required fields absent from `properties`, undescribed parameters,
generic parameter names such as `data`, `input`, `value`, and `payload`,
undescribed `anyOf`/`oneOf` variants when at least one undescribed variant is
structural (an object, array or `$ref`; a union of scalar types explains itself),
and nested objects without descriptions. Boolean property schemas are skipped.
It is not full JSON Schema validation or an oracle for a tool's implementation.

</details>

[All scan rules](/rules) · [Quickstart](/docs/quickstart) · [Separate preflight checks](/docs/preflight).