vmware-debug 1.10.0__tar.gz → 1.11.1__tar.gz

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==1.10.0",
+        "vmware-debug==1.11.1",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 1.10.0
+Version: 1.11.1
 Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug
@@ -18,7 +18,7 @@ Requires-Dist: mcp[cli]<2.0,>=1.10
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-policy<2.0,>=1.8.5
+Requires-Dist: vmware-policy<2.0,>=1.10.0
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.vmware-skills/vmware-debug -->

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/RELEASE_NOTES.md

@@ -1,3 +1,70 @@
+## v1.11.1 — the schema an agent reads now carries the descriptions
+
+Parameter descriptions reach the JSON schema for the first time. An MCP client
+sees the schema, not the docstring, and this repo's coverage of `description`
+and `additionalProperties` was 0% — while nearly every parameter was already
+described in an `Args:` block no client ever receives.
+
+Measured on a real VCF 9.1 estate, the gap produced a silent failure with no
+error at any stage: a parameter name guessed wrong is discarded and the tool
+returns the full unfiltered result; a value guessed wrong (`power_state=
+"running"`) returns 0 rows where there were 11.
+
+vmware-policy 1.10.0's `describe_tool_parameters` copies what is already
+written, so the docstring is now load-bearing and the two cannot drift apart. It
+removes the `Args:` block from the description once copied — both travel in
+every `tools/list` response, so leaving it bills the same sentences twice
+against the manifest's token budget. `additionalProperties` is closed: an open
+schema is room for a model to invent arguments that are then silently
+discarded, which is the other half of the same failure.
+
+**The `vmware-policy` floor moves to >=1.10.0.** Older releases have no
+`describe_tool_parameters`, and resolving one gives an ImportError at server
+start rather than a missing feature.
+
+
+## v1.11.0 — the correlation engine, on a real incident
+
+A tester fed the investigation layer a genuine failure: on 08-03 at 05:49, four
+ESXi hosts went `EnteringMaintenanceMode` → `EnteredMaintenanceMode` →
+`HostShutdown` → `HostConnectionLost` → `HostSyncFailed` ×24 within 32 seconds,
+and never came back. 3,818 real vCenter events over 40 days, pulled per this
+skill's own envelope documentation. The case-management layer held up. The
+correlation engine — the thing this skill is named for — did not.
+
+**80% of events were `uncategorized`, and the headline conclusion was "cannot
+classify, widen your search window".** The classification table's
+`power_lifecycle` keywords were all VM-centric (`power on`/`power off`, `vmx`,
+`ovf`, `clone`, `snapshot`); nothing covered host maintenance mode or host
+shutdown, and `"Shut down of esxi05"` does not match `"power off"`. There is now
+a `host_lifecycle` category — a separate category rather than more keywords,
+because it is a separate investigation, routed to monitor + logs + harden (a
+host that left service on cue was usually told to). `classification_coverage()`
+reports what went unread in every result, and above ~25% it reaches
+`next_checks`. The "widen the window" remedy is gone: the window was already 40
+days, and widening makes the incident *less* findable.
+
+**The only spike detected was the day the hosts came back up.**
+`_auto_bin_seconds` was `span/30`, so a 29-day window gave 23.2-hour buckets;
+the incident hour was the second-busiest in the dataset and absent from the
+spike list, while `--bin-seconds 3600` found it at z=8.25. Binning now chooses
+by event *density*, from a floor of 4 events per bin that is derived rather than
+tuned: spikes flag at mean+2σ, and a count only exceeds twice its mean once the
+mean reaches 4. The chosen width, how it was chosen, and the bin count are
+reported.
+
+**The same incident described five ways routed five different ways** — decided
+by an incidental noun, with the most accurate description routing nowhere.
+Categories are now ranked by matched-keyword length, so a long phrase beats a
+stray word, and the losing categories are named.
+
+Also fixed: `case_timeline`'s payload contract was undocumented and its MCP
+parameter type refused the array shape the docstring implied; pure-Chinese
+summaries collapsed to one `case_id` per second, with a collision message that
+was false; and skill names were compared as raw strings, so `monitor` and
+`vmware-monitor` counted as two independent evidence sources — buying *Probable*
+out of orthography, in the layer built to prevent exactly that.
+
 ## v1.10.0 — the knowledge layer is implemented, not just described
 
 v1.9.0 shipped the investigation layer with `applies_to` documented as the thing

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.10.0"
+version = "1.11.1"
 description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,7 @@ dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
     "mcp[cli]>=1.10,<2.0",
-    "vmware-policy>=1.8.5,<2.0",
+    "vmware-policy>=1.10.0,<2.0",
     # Imported directly by ops/cases/grading.py for the rules file. It has
     # always arrived transitively via vmware-policy; a package should
     # declare what it imports rather than rely on a dependency's dependency.

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/server.json

@@ -7,12 +7,21 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "1.10.0",
+  "version": "1.11.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.10.0",
+      "version": "1.11.1",
+      "runtimeHint": "uvx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "valueHint": "subcommand",
+          "value": "mcp",
+          "description": "Starts the stdio MCP server. Without it the console script runs the human CLI and exits."
+        }
+      ],
       "transport": {
         "type": "stdio"
       }

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/skills/vmware-debug/SKILL.md

@@ -256,8 +256,10 @@ vmware-debug mcp                                # start stdio MCP server (proxy-
 ## Troubleshooting
 
 - **`incident_timeline` raises "event[N] could not be normalised"** — event N is missing a timestamp or has an unparseable one. Every event needs `ts` (ISO-8601, epoch seconds, or millis).
-- **All hypotheses come back "uncategorized"** — the symptom isn't in the catalogue yet; widen the window and pull from another source (aria anomalies, log-insight). Consider adding a signature (see `references/routing.md`).
-- **No spikes detected on an obvious burst** — you need ≥3 time bins for a baseline; shrink `bin_seconds`.
+- **Most events come back "uncategorized"** — read `classification` in the result: it says how many, what share, and quotes the texts that matched nothing. Do **not** widen the window; a wider window adds baseline, not signal. The spikes still tell you *when*, which is answerable without a category. If the samples name a subsystem the taxonomy does not know, add a signature (see `references/routing.md`).
+- **No spikes detected on an obvious burst** — check `binning` for the resolution you were given. The width is chosen from event density so that bins average ≥4 events; a burst shorter than one bin can still be flattened by it. Pass `bin_seconds` to narrow. Below three bins there is no baseline at all and nothing is reported.
+- **`case_timeline` says zero events after you submitted results** — check `payload_events` in each `case_submit_evidence` reply. Events are read from a bare list, or from `items`/`events`/`rows`; a *summary* of a tool's result carries none. `note` names which items carried nothing and what keys they held instead.
+- **`case_readiness` says a skill you have is not installed** — both spellings are accepted (`monitor` and `vmware-monitor`). A name it did not recognise comes back in `unrecognised_skills` rather than being read as missing.
 - **It won't execute the fix** — by design. Route to vmware-aiops or vmware-pilot.
 
 ## Audit & Safety

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/skills/vmware-debug/references/capabilities.md

@@ -27,9 +27,16 @@ fixed in-process constant, so `total` is a real count and `limit` is `null`.
 
 ## Symptom categories
 
-`storage`, `network`, `compute`, `ha_drs`, `power_lifecycle`, `auth`, `platform`.
+`storage`, `network`, `compute`, `ha_drs`, `host_lifecycle`, `power_lifecycle`,
+`auth`, `platform`.
 See `references/routing.md` for keyword signatures and the skill each routes to.
 
+`host_lifecycle` is a host changing its own availability state — maintenance
+mode, shutdown, reboot, standby, connection loss, sync failure.
+`power_lifecycle` is the VM-level equivalent. They are separate because they are
+separate investigations: the second is a task question for vmware-aiops, the
+first is a cluster, DPM, vLCM or drift question.
+
 ## Design properties
 
 - **Zero cross-skill runtime deps** — correlation is pure functions over plain

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/skills/vmware-debug/references/event-envelope.md

@@ -21,7 +21,7 @@ runtime dependency** on the other packages (no version lockstep, no heavy instal
 | Field | Type | Notes |
 |---|---|---|
 | `ts` | string \| number | ISO-8601, epoch **seconds**, or epoch **millis** (auto-detected). Required. |
-| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... |
+| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... The catalogue in `rules/evidence_sources.yaml` spells the same skills `vmware-monitor`, `vmware-aria`, `vmware-log-insight`. Both spellings are understood wherever a skill is named — `case_readiness(available_skills=...)`, and the grader's count of independent sources, which treats two spellings of one skill as one source. |
 | `severity` | string | Free text; normalised to `critical`/`error`/`warning`/`info`/`unknown`. |
 | `entity` | string | The object the event is about (VM/host/datastore). May be empty. |
 | `text` | string | Human-readable message — this is what the symptom classifier matches on. |

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/skills/vmware-debug/references/routing.md

@@ -10,6 +10,7 @@ Keep this in sync with `_CATEGORY_SIGNATURES` in `vmware_debug/ops/timeline.py`
 | **network** | vmotion, uplink, link down, mtu, firewall, dfw, segment, tier-0, bgp | vmware-nsx, vmware-nsx-security (traceflow, DFW hits) | pilot |
 | **compute** | cpu ready, memory, balloon, swap, contention, numa | vmware-aria (metrics + anomalies) | pilot (rightsizing) |
 | **ha_drs** | ha, high availability, drs, failover, admission control, isolation | vmware-monitor, vmware-aiops (cluster) | pilot |
+| **host_lifecycle** | maintenance mode, shut down of, host reboot, standby mode, lost connection to, cannot synchronize, not responding | vmware-monitor (host/cluster state), vmware-harden (drift — a host that left service on cue was told to), vmware-log-insight (vpxd/hostd) | pilot |
 | **power_lifecycle** | power on/off, failed to start, boot, vmx, ovf, clone, snapshot | vmware-aiops (task status, snapshot tree), vmware-monitor | aiops |
 | **auth** | login, authentication, denied, 401, 403, token, certificate, tls | config/.env, target cert + time sync | config fix |
 | **platform** | vpxd, hostd, service restart, crash, 503, not responding, disconnected | vmware-monitor (connection/service), vmware-log-insight (vpxd/hostd) | pilot |

{vmware_debug-1.10.0 → vmware_debug-1.11.1}/tests/eval/capability/_scores.json

@@ -94,7 +94,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:56"
+            "where": "grading.py:57"
           },
           {
             "message": "grading_rules.yaml at {} is not valid YAML: {}. Fix it rather than deleting it \u2014 falling back to the",
@@ -102,7 +102,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:58"
+            "where": "grading.py:59"
           },
           {
             "message": "A hypothesis needs a statement \u2014 what you think happened, in one line. An unnamed hypothesis cannot ",
@@ -135,7 +135,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "plan.py:72"
+            "where": "plan.py:84"
           },
           {
             "message": "evidence_sources.yaml at {} is missing 'classes' or 'routing'. An empty catalogue would make every r",
@@ -167,7 +167,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:140"
+            "where": "timeline.py:137"
           },
           {
             "message": "Cannot read case.json for {}: {}",
@@ -175,7 +175,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:154"
+            "where": "timeline.py:151"
           }
         ],
         "per_dimension_pct": {
@@ -193,58 +193,47 @@
     "manifest_context_headroom": {
       "detail": {
         "heaviest_tools": {
-          "case_open": 354,
-          "case_plan": 360,
-          "case_record_gap": 337,
-          "case_submit_evidence": 621,
-          "incident_timeline": 329
+          "case_open": 478,
+          "case_plan": 444,
+          "case_record_gap": 380,
+          "case_submit_evidence": 902,
+          "incident_timeline": 454
         },
-        "manifest_tokens": 3777,
-        "mean_tokens_per_tool": 269.8,
+        "manifest_tokens": 4812,
+        "mean_tokens_per_tool": 343.7,
         "reference_context": 16384,
         "tool_count": 14
       },
       "maximum": 16384,
-      "pct": 76.9,
+      "pct": 70.6,
       "unit": "tokens",
-      "value": 12607
+      "value": 11572
     },
     "parameter_documentation_coverage": {
       "detail": {
-        "undocumented_by_tool": {
-          "case_grade": [
-            "case_id"
-          ],
-          "case_submit_evidence": [
-            "fetched_at",
-            "summary"
-          ],
-          "case_timeline": [
-            "bin_seconds",
-            "case_id",
-            "top_n",
-            "z_threshold"
-          ]
-        }
+        "undocumented_by_tool": {}
       },
       "maximum": 45,
-      "pct": 84.4,
+      "pct": 100.0,
       "unit": "parameters",
-      "value": 38
+      "value": 45
     },
     "per_tool_token_discipline": {
       "detail": {
         "ceiling": 350,
         "over_ceiling": {
-          "case_open": 354,
-          "case_plan": 360,
-          "case_submit_evidence": 621
+          "case_open": 478,
+          "case_plan": 444,
+          "case_record_gap": 380,
+          "case_submit_evidence": 902,
+          "case_timeline": 374,
+          "incident_timeline": 454
         }
       },
       "maximum": 14,
-      "pct": 78.6,
+      "pct": 57.1,
       "unit": "tools",
-      "value": 11
+      "value": 8
     },
     "read_only_manifest_saving": {
       "detail": {
@@ -281,7 +270,7 @@
           "evidence.py:179",
           "evidence.py:211",
           "evidence.py:248",
-          "grading.py:66",
+          "grading.py:67",
           "hypotheses.py:47",
           "hypotheses.py:70"
         ]
@@ -301,48 +290,37 @@
     "tool_description_quality": {
       "detail": {
         "per_dimension_pct": {
-          "args": 78.6,
-          "gotcha": 85.7,
+          "args": 100.0,
+          "gotcha": 100.0,
           "marker": 100.0,
-          "next_hop": 57.1,
+          "next_hop": 78.6,
           "what": 100.0,
           "when": 92.9
         },
         "tools_graded": 14,
         "weakest_tools": {
-          "case_close": [
-            "next_hop"
-          ],
-          "case_get": [
-            "gotcha"
-          ],
-          "case_grade": [
-            "args",
-            "next_hop"
-          ],
+          "case_close": [],
+          "case_get": [],
+          "case_grade": [],
+          "case_hypotheses": [],
           "case_knowledge": [
             "next_hop"
           ],
           "case_list": [
-            "gotcha",
             "next_hop"
           ],
           "case_readiness": [
             "next_hop"
           ],
           "case_record_gap": [
-            "next_hop",
             "when"
-          ],
-          "case_submit_evidence": [
-            "args"
           ]
         }
       },
       "maximum": 84,
-      "pct": 85.7,
+      "pct": 95.2,
       "unit": "points",
-      "value": 72
+      "value": 80
     },
     "tool_failure_payload_quality": {
       "detail": {

vmware_debug-1.11.1/tests/eval/regression/test_case_id_non_ascii.py

@@ -0,0 +1,86 @@
+"""A case opened in Chinese got no identity of its own.
+
+``slugify`` reduces on ``[^a-z0-9]+``, so a summary written entirely in Chinese
+leaves nothing behind and the id falls back to the literal word ``case``:
+``20260830-061014-case``. Two completely different investigations opened in the
+same second then collide — and the collision message said they were "the same
+summary", which was false, and sent the reporter looking for a duplicate that
+did not exist.
+
+The id has to stay inside its character set: it is a directory name, and
+``validate_case_id`` is the only thing between a model-chosen string and
+``open(root / case_id)``. So the fix is not to widen the alphabet. It is that an
+id must distinguish summaries that differ, and that the collision message must
+describe what actually collided.
+
+The control is readability: an ASCII summary must still produce the readable
+slug the listing was designed around, not a digest for everybody.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vmware_debug.ops.cases.ids import new_case_id, validate_case_id
+from vmware_debug.ops.cases.model import Scope
+from vmware_debug.ops.cases.store import CaseExists, create_case
+
+AT = "2026-08-30T06:10:14Z"
+
+#: Both must be free of Latin characters. An earlier draft wrote the first one
+#: as "四台 ESXi 主机…", and "esxi" survived slugify — so the two ids differed
+#: whatever the fallback did, and the test passed against the defect it was
+#: written to catch.
+ZH_A = "四台主机同时进入维护模式后关机"
+ZH_B = "存储集群延迟升高导致虚拟机无响应"
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_HOME", str(tmp_path / "vmware"))
+
+
+class TestANonAsciiSummaryStillGetsAnIdentity:
+    def test_two_different_chinese_summaries_do_not_collide(self):
+        assert new_case_id(ZH_A, AT) != new_case_id(ZH_B, AT)
+
+    def test_the_id_is_still_a_safe_directory_name(self):
+        validate_case_id(new_case_id(ZH_A, AT))
+
+    def test_the_same_summary_still_yields_the_same_id(self):
+        """Ids are replayable: a case folder re-opened from its scope has to
+        reconstruct the id it already has."""
+        assert new_case_id(ZH_A, AT) == new_case_id(ZH_A, AT)
+
+    def test_both_cases_can_actually_be_opened_in_the_same_second(self):
+        create_case(Scope(summary=ZH_A, determined_by="user report"), at=AT)
+        create_case(Scope(summary=ZH_B, determined_by="user report"), at=AT)
+
+
+class TestTheCollisionMessageIsTrue:
+    def test_it_does_not_claim_the_summaries_were_identical(self):
+        """Two summaries that differ only outside the id character set still
+        collide, and telling the reporter they submitted the same summary sends
+        them looking for something that is not there."""
+        create_case(Scope(summary="vsan latency!", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency?", determined_by="a"), at=AT)
+        assert "same summary" not in str(exc.value)
+
+    def test_it_says_what_to_do_about_it(self):
+        create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        assert "case_get" in str(exc.value)
+
+
+class TestControlReadabilityIsNotSacrificed:
+    def test_an_ascii_summary_still_gets_its_readable_slug(self):
+        """A digest for every case would pass every test above and destroy the
+        one property the slug exists for — a directory listing you can read."""
+        assert new_case_id("vSAN datastore latency on cluster-01", AT).endswith(
+            "-vsan-datastore-latency-on-cluster-01"
+        )
+
+    def test_a_mixed_summary_keeps_the_part_that_survives(self):
+        assert "esxi05" in new_case_id("主机 esxi05 关机", AT)

vmware_debug-1.11.1/tests/eval/regression/test_every_tool_parameter_is_documented.py

@@ -0,0 +1,132 @@
+"""Regression: every MCP tool parameter carries a Google-style ``Args:`` entry.
+
+Why this exists
+---------------
+The JSON schema is the only part of a tool an agent can actually read. Prose in
+the docstring body explains the tool; it says nothing about a *parameter*. A
+measurement across the family's 327 tools found ``description`` coverage on
+parameter schemas at 0% — every word of guidance was in prose the schema never
+carried — and every one of this skill's 45 parameters was undescribed — including
+``case_plan.category`` and ``case_submit_evidence.source_skill``, both of
+which have a closed set of legal values that appeared nowhere in the schema.
+
+The failure that produces is silent twice over. Guess a parameter name wrong
+and the extra key is discarded, so a filtered query quietly returns the
+unfiltered set. Guess a *value* wrong — ``aggregation="count()"`` where the
+appliance wants ``COUNT`` — and you get an error or an empty series where there
+was data. Neither looks like a mistake from the outside.
+
+The family is landing a shared helper that copies each parameter's ``Args:``
+entry into the schema at registration time. That helper can only copy text that
+exists, so this test guards the input side: it fails the moment a tool grows a
+parameter nobody described.
+
+Not a style check
+-----------------
+It also refuses a description that only restates the name (``target: The
+target.``). That is worse than an absent one: it fills the slot, so the gap
+stops being visible while the agent still learns nothing.
+
+形态 #1 — the check must not pass vacuously. If the registry hands back no
+tools, or no tool has parameters, that is this test being broken rather than
+this skill being clean, and it fails saying so.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+
+from vmware_debug.mcp_server.server import build_server
+
+#: Words that carry no information about a parameter beyond its own name.
+#: A description built only from these has filled the slot without saying
+#: anything — the shape this test exists to reject.
+_FILLER = {"a", "an", "the", "of", "for", "to", "this", "s", "id", "name", "optional"}
+
+
+def parse_args_block(doc: str | None) -> dict[str, str]:
+    """Return {parameter: description} from a Google-style ``Args:`` block.
+
+    Deliberately the same parsing the family's schema-injection helper does:
+    a check that reads docstrings differently from the code that consumes them
+    would go green on text the helper cannot use.
+    """
+    if not doc:
+        return {}
+    block = re.search(
+        r"\n\s*Args:\s*\n(.*?)(?:\n\s*(?:Returns|Raises|Yields|Examples?|Notes?):|\Z)",
+        doc,
+        re.DOTALL,
+    )
+    if not block:
+        return {}
+    out: dict[str, str] = {}
+    current: str | None = None
+    for line in block.group(1).splitlines():
+        if not line.strip():
+            continue
+        entry = re.match(r"\s{4,}(\*{0,2}\w+)\s*(?:\([^)]*\))?\s*:\s*(.*)", line)
+        if entry:
+            current = entry.group(1).lstrip("*")
+            out[current] = entry.group(2).strip()
+        elif current:
+            out[current] += " " + line.strip()
+    return out
+
+
+def _says_something(param: str, text: str) -> bool:
+    """True when the description adds anything beyond the parameter's own name.
+
+    Deliberately the weakest rule that still catches ``target: The target.`` —
+    one word that is neither part of the name nor a connective. A stricter
+    length or word-count rule would start failing short descriptions that are
+    complete ("Server IP address."), and a check that fires on correct text is
+    a check people learn to route around.
+    """
+    words = {w for w in re.findall(r"[a-z0-9]+", text.lower()) if w}
+    words -= _FILLER
+    words -= set(re.findall(r"[a-z0-9]+", param.lower()))
+    return bool(words)
+
+
+def test_every_tool_parameter_has_an_args_entry():
+    """No registered tool parameter may be missing from its ``Args:`` block."""
+    tools = build_server()._tool_manager._tools
+    assert tools, "no MCP tools registered — this check would pass vacuously"
+
+    checked = 0
+    missing: list[str] = []
+    for name, tool in tools.items():
+        documented = parse_args_block(inspect.getdoc(tool.fn))
+        for param in (tool.parameters or {}).get("properties", {}):
+            checked += 1
+            if param not in documented:
+                missing.append(f"{name}.{param}")
+
+    assert checked, "no tool parameters found — this check would pass vacuously"
+    assert not missing, (
+        f"{len(missing)} of {checked} tool parameters have no Args: entry, so the "
+        f"schema an agent reads describes them not at all: {sorted(missing)}"
+    )
+
+
+def test_no_parameter_description_merely_restates_its_name():
+    """A description that only echoes the name hides the gap instead of closing it."""
+    tools = build_server()._tool_manager._tools
+    assert tools, "no MCP tools registered — this check would pass vacuously"
+
+    checked = 0
+    empty: list[str] = []
+    for name, tool in tools.items():
+        documented = parse_args_block(inspect.getdoc(tool.fn))
+        for param in (tool.parameters or {}).get("properties", {}):
+            text = documented.get(param)
+            if text is None:
+                continue  # the test above owns this failure
+            checked += 1
+            if not _says_something(param, text):
+                empty.append(f"{name}.{param}: {text!r}")
+
+    assert checked, "no documented parameters found — this check would pass vacuously"
+    assert not empty, "parameter descriptions that say nothing beyond the name: " + str(empty)