fix: remove top-level parameter descriptions from capabilities

Author: BB-84C

CHANGELOG.md

@@ -10,6 +10,6 @@ All notable changes to this project are documented in this file.
 ### Changed
 - Updated `docs/release_private_index.md` to list required pre-release verification commands: `ruff check .`, `black --check .`, `mypy nanonis_qcodes_controller`, `pytest`, and `python -m build`.
 - Expanded distribution readiness documentation and release tracking with concrete private-index release verification notes.
-- Updated `nqctl capabilities` to expose rich `parameters.items[*]` metadata (`get_cmd`, `set_cmd`, validators, safety, descriptions) for agent-driven planning of `get`/`set`/`ramp`.
-- Updated `nqctl capabilities` to omit empty `description` fields and fall back to non-empty command descriptions when top-level parameter descriptions are missing.
+- Updated `nqctl capabilities` to expose rich `parameters.items[*]` metadata (`get_cmd`, `set_cmd`, validators, safety) for agent-driven planning of `get`/`set`/`ramp`.
+- Updated `nqctl capabilities` to remove top-level parameter `description` output and keep descriptions on `get_cmd`/`set_cmd` only.
 - Updated GitHub-release install examples in `README.md` to use `<version>` placeholders.

docs/cli_contract.md

@@ -5,8 +5,8 @@ Expose a small, stable command surface that orchestration agents can call direct
 
 ## Core commands
 - `nqctl capabilities`: returns parameters/actions/policy summary, including rich
-  `parameters.items[*]` metadata (`get_cmd`, `set_cmd`, `vals`, `safety`, non-empty descriptions)
-  for agent planning.
+  `parameters.items[*]` metadata (`get_cmd`, `set_cmd`, `vals`, `safety`) for
+  agent planning. Descriptions are exposed on `get_cmd`/`set_cmd` when present.
 - `nqctl observables list`: returns readable and writable parameter metadata.
 - `nqctl actions list`: returns supported action descriptors.
 - `nqctl get <parameter>`: reads one parameter value.

nanonis_qcodes_controller/cli.py

@@ -1242,14 +1242,6 @@ def _collect_parameter_capabilities(instrument: Any) -> list[dict[str, Any]]:
             "safety": safety,
         }
 
-        description = _optional_text(spec.description)
-        if description is None and get_cmd is not None:
-            description = _optional_text(get_cmd.get("description"))
-        if description is None and set_cmd is not None:
-            description = _optional_text(set_cmd.get("description"))
-        if description is not None:
-            capability["description"] = description
-
         capabilities.append(capability)
     return capabilities
 

nanonis_qcodes_controller/resources/config/parameters.yaml

@@ -7881,8 +7881,6 @@ parameters:
     label: Zspectr Retractsecond
     unit: ''
     type: int
-    description: Configuration for the Second condition of Auto Retract in the
-      Z-Spectroscopy module.
     get_cmd:
       command: ZSpectr_RetractSecondGet
       payload_index: 0

nanonis_qcodes_controller/version.py

@@ -1 +1 @@
-__version__ = "0.1.2"
+__version__ = "0.1.3"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nanonis-qcodes-controller"
-version = "0.1.2"
+version = "0.1.3"
 description = "Simulator-first bridge between Nanonis SPM and QCodes"
 readme = "README.md"
 requires-python = ">=3.10"

tests/test_cli.py

@@ -129,7 +129,7 @@ def fake_print_payload(payload, *, as_json: bool) -> None:
     assert isinstance(items, list)
     parameter = items[0]
     assert parameter["name"] == "bias_v"
-    assert parameter["description"] == "Tip-sample bias voltage."
+    assert "description" not in parameter
     assert parameter["get_cmd"]["command"] == "Bias.Get"
     assert parameter["get_cmd"]["description"] == "Read configured bias voltage."
     assert parameter["get_cmd"]["args"] == {"channel": 1}
@@ -139,7 +139,7 @@ def fake_print_payload(payload, *, as_json: bool) -> None:
     assert parameter["vals"]["kind"] == "numbers"
 
 
-def test_capabilities_falls_back_to_command_description_and_drops_empty_fields(monkeypatch) -> None:
+def test_capabilities_drops_top_level_description_and_empty_nested_fields(monkeypatch) -> None:
     spec = ParameterSpec(
         name="zspectr_retractsecond",
         label="Zspectr Retractsecond",
@@ -211,7 +211,8 @@ def fake_print_payload(payload, *, as_json: bool) -> None:
     items = parameters_payload["items"]
     assert isinstance(items, list)
     parameter = items[0]
-    assert parameter["description"] == (
+    assert "description" not in parameter
+    assert parameter["get_cmd"]["description"] == (
         "Returns the configuration for the Second condition of the Auto Retract "
         "in the Z-Spectroscopy module."
     )