witan-code 0.13.3__tar.gz → 0.13.4__tar.gz

{witan_code-0.13.3 → witan_code-0.13.4}/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
 a MINOR bump may include breaking changes).
 
+## [0.13.4] - 2026-08-19
+
+### Changed
+
+- **Every `code_*` tool parameter now carries a description in its JSON
+  Schema.** Seven parameters across seven tools had none — the `symbol_id`
+  argument of `code_callers`, `code_find_references`, `code_impact`, and
+  `code_cross_repo_impact`, the `repo` filter on `code_find_definition` and
+  `code_search_symbol`, and `branch` on `code_indexed_branches`. FastMCP
+  sends these schemas to the model, so an undescribed parameter leaves the
+  calling agent guessing. `symbol_id` in particular now says where the value
+  comes from (the `symbol_id` field of `code_find_definition` /
+  `code_search_symbol`) and what shape it has.
+
 ## [0.13.3] - 2026-08-18
 
 ### Changed

{witan_code-0.13.3 → witan_code-0.13.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: witan-code
-Version: 0.13.3
+Version: 0.13.4
 Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
 Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
 Project-URL: Repository, https://github.com/mitodl/agent-kit

{witan_code-0.13.3 → witan_code-0.13.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "witan-code"
-version = "0.13.3"
+version = "0.13.4"
 description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -162,7 +162,7 @@ testpaths = ["tests"]
 packages = ["witan_code"]
 
 [tool.bumpversion]
-current_version = "0.13.3"
+current_version = "0.13.4"
 allow_dirty = true
 
 [[tool.bumpversion.files]]

witan_code-0.13.4/tests/test_tool_schema.py

@@ -0,0 +1,49 @@
+"""Every `code_*` tool parameter must carry a description in its schema.
+
+The witan-council twin of this file explains the reasoning at length; briefly:
+FastMCP derives each tool's JSON Schema from its docstring's numpydoc
+``Parameters`` section, and that schema is what the calling model sees. Seven
+parameters here — including the ``symbol_id`` of ``code_callers``,
+``code_find_references``, ``code_impact`` and ``code_cross_repo_impact`` —
+reached the model with nothing but a name and a type, and the existing
+``list_tools`` coverage asserts only that ``code_reindex`` exists, so a
+regression would not have been reported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def _tool_properties() -> list[tuple[str, str, dict]]:
+    """(tool, parameter, schema) for every exposed parameter of every tool."""
+    from witan_code import server as code_server
+
+    tools = asyncio.run(code_server.mcp._list_tools())
+    return [
+        (tool.name, name, schema)
+        for tool in tools
+        for name, schema in ((tool.parameters or {}).get("properties", {})).items()
+    ]
+
+
+def test_every_tool_parameter_has_a_description():
+    missing = [
+        f"{tool}.{param}"
+        for tool, param, schema in _tool_properties()
+        if not (schema.get("description") or "").strip()
+    ]
+    assert not missing, (
+        f"{len(missing)} tool parameter(s) reach the model with no description. "
+        "Add a numpydoc `Parameters` entry for each in witan_code/server.py:\n  "
+        + "\n  ".join(sorted(missing))
+    )
+
+
+def test_the_tool_surface_is_actually_being_inspected():
+    """Guard the guard — an empty listing would make the assertion vacuous."""
+    properties = _tool_properties()
+    assert len(properties) > 20, (
+        f"only {len(properties)} tool parameters found; the code_* surface is "
+        "larger than that, so the schema inspection is probably broken"
+    )

{witan_code-0.13.3 → witan_code-0.13.4}/witan_code/server.py

@@ -424,6 +424,12 @@ async def code_find_definition(
     ----------
     name:
         Bare name (``run``) or qualified name (``Service.run``).
+    repo:
+        Canonical repo URI to search. Defaults to the repo detected from the
+        checkout, and fans out across every indexed repo only when no repo is
+        detected at all. Note this differs from the witan memory/task tools:
+        ``repo=""`` does **not** force a fan-out here — it is falsy, so it
+        behaves exactly like omitting the argument.
     branch:
         Git branch whose indexed view to query (e.g. another agent's in-flight
         branch). Defaults to the checkout's branch when querying the current
@@ -464,6 +470,13 @@ async def code_find_references(
 
     Supersets code_callers (references includes calls); use code_callers when
     you want calls only. Heuristic — may miss or over-report.
+
+    Parameters
+    ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
     """
     client = _client_for_symbol(symbol_id)
     if client is None:
@@ -483,6 +496,13 @@ async def code_callers(symbol_id: str, ctx: Context | None = None) -> list[dict]
 
     Heuristic name-resolution based; not a precise call graph. For calls plus
     other references use code_find_references.
+
+    Parameters
+    ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
     """
     client = _client_for_symbol(symbol_id)
     if client is None:
@@ -508,6 +528,12 @@ async def code_impact(
 
     Parameters
     ----------
+    symbol_id:
+        The symbol to start from, as returned in the ``symbol_id`` field of
+        code_find_definition or code_search_symbol. Form:
+        ``<repo>#<path/to/file.py>::<QualifiedName>``.
+        This is the symbol you are about to change; the result is its blast
+        radius.
     max_depth:
         Maximum BFS depth (default 5).
     max_nodes:
@@ -635,6 +661,13 @@ def code_search_symbol(
         ``class``, ``module``, ``variable``, ``interface``, ``type``, ``enum``,
         ``key``, ``table``, ``cte``, or ``block``. Pass e.g. ``kind="function"``
         to exclude the many YAML ``key`` symbols when searching for code.
+    repo:
+        Canonical repo URI to search. Defaults to the repo detected from the
+        checkout, and fans out across every indexed repo only when no repo is
+        detected at all — ``repo=""`` does **not** force that, unlike the witan
+        memory/task tools; it is falsy and behaves like omitting the argument.
+        BM25 ranking is per-store, so a fan-out concatenates each store's
+        ranked results rather than producing one global ordering.
     branch:
         Git branch whose indexed view to query. Defaults to the checkout's
         branch when querying the current repo; when ``repo`` names a different
@@ -767,6 +800,11 @@ async def code_cross_repo_impact(
 
     Parameters
     ----------
+    symbol_id:
+        The symbol whose cross-repo surface to trace, as returned in the
+        ``symbol_id`` field of code_find_definition or code_search_symbol. Its
+        repo prefix also scopes the bridge read, so asking about another repo's
+        symbol does not pick up an unrelated overlay from your own checkout.
     min_precision:
         ``heuristic`` (default) | ``precise`` — see server instructions.
     """
@@ -1018,6 +1056,13 @@ def code_indexed_branches(branch: str | None = None) -> list[dict]:
     sanitized git branch it is a view of, ``actor`` its owner (null on a
     single-writer local store). ``views`` is null for a store that could not be
     listed.
+
+    Parameters
+    ----------
+    branch:
+        A raw git branch name (not a view name) to filter by, showing every
+        writer's view of that one branch — this is how you find a teammate's
+        in-flight work. Omit to list every view of every indexed repo.
     """
     wanted = repo_module.branch_store_name(branch) if branch else None