descry-codegraph 0.3.0__tar.gz → 0.3.1__tar.gz

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-10-22
+
+### Fixed
+
+- The callers a change lists (`changes`), and those `context` lists and
+  counts and an upstream `flow` follows, are the callers of that symbol,
+  not of every symbol of its name. `context` marks a caller that reaches
+  the symbol only as one of an unresolved call's candidates, as `callers`
+  does.
+- A symbol's caller count (`in_degree`, shown as "N callers") counts the
+  symbols that call or construct it, not every edge into it: the file
+  defining it was counted as a caller.
+- A Python signature is written as the source writes it, with defaults,
+  `*`, `**`, keyword-only parameters and `async`, and with no `-> None`
+  where no return type is annotated. An unannotated function was recorded
+  as returning `None`.
+- The web UI's Language filter lists the graph's languages, which the
+  graph status now gives (`/api/status`, `/api/health`), instead of four
+  fixed ones.
+- A search during the startup pre-warm, or during the embeddings load
+  after an index, waits for that load (up to `embedding_timeout`) instead
+  of reporting that embeddings are loading. A streamed index reports the
+  embeddings line however long the load takes.
+- scip-python runs without `pip` on PATH and outside a git repository: it
+  is given an empty environment and a project version.
+- A SCIP indexer's failure is reported by its error, without the stack
+  frames that pushed it out of the message.
+- `flatten` takes a class name as `context` does, not only a node ID.
+- `impls` says trait implementations are recorded for Rust only, instead
+  of advising a reindex.
+- An unresolved call with one candidate reads "unresolved; the only
+  candidate", not "one of 1 candidates".
+
 ## [0.3.0] — 2026-10-22
 
 Call resolution is rebuilt for every supported language: a call is

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/CLAUDE.md

@@ -23,7 +23,7 @@ just test tests/test_handlers.py::test_index     # one test
 just test -k "cross_lang and not slow"           # by expression
 ```
 
-Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (2722 tests currently — a drop is a regression signal).
+Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (2755 tests currently — a drop is a regression signal).
 
 Invoke the tool while developing:
 

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 0.3.0
+Version: 0.3.1
 Summary: Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis
 Project-URL: Homepage, https://github.com/06chaynes/descry
 Project-URL: Repository, https://github.com/06chaynes/descry
@@ -251,7 +251,7 @@ Descry provides 19 tools, available through all interfaces:
 | `path` | Find shortest call path between two symbols |
 | `structure` | Show file structure — imports, classes, functions |
 | `flatten` | Show effective API of a class including inherited methods |
-| `impls` | Find all implementations of a trait/interface method |
+| `impls` | Find all implementations of a Rust trait method |
 | `cross-lang` | Trace frontend API calls to backend handlers via OpenAPI |
 | `churn` | Find code churn hotspots (symbols, files, or co-change pairs) |
 | `evolution` | Track how a symbol has changed over time |

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/README.md

@@ -186,7 +186,7 @@ Descry provides 19 tools, available through all interfaces:
 | `path` | Find shortest call path between two symbols |
 | `structure` | Show file structure — imports, classes, functions |
 | `flatten` | Show effective API of a class including inherited methods |
-| `impls` | Find all implementations of a trait/interface method |
+| `impls` | Find all implementations of a Rust trait method |
 | `cross-lang` | Trace frontend API calls to backend handlers via OpenAPI |
 | `churn` | Find code churn hotspots (symbols, files, or co-change pairs) |
 | `evolution` | Track how a symbol has changed over time |

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "0.3.0"
+version = "0.3.1"
 description = "Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis"
 requires-python = ">=3.11"
 authors = [{name = "Christian Haynes"}]

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/__init__.py

@@ -1,4 +1,4 @@
 """Descry — Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __all__ = ["__version__"]

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/_graph.py

@@ -11,6 +11,11 @@ from pathlib import Path
 
 CURRENT_SCHEMA = 2
 
+# The edges by which one symbol calls or constructs another: its callers
+CALL_RELATIONS = frozenset(
+    {"CALLS", "CALLS_RESOLVED", "INSTANTIATES", "INSTANTIATES_RESOLVED"}
+)
+
 
 class GraphSchemaError(Exception):
     """Raised when a graph file is not a graph this version can read.

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/cli.py

@@ -368,7 +368,7 @@ def main():
 
     # impls
     sub = subparsers.add_parser(
-        "impls", help="Find all implementations of a trait method"
+        "impls", help="Find all implementations of a Rust trait method"
     )
     sub.add_argument("method", help="Method name")
     sub.add_argument("--trait-name", default=None, help="Filter by trait name")

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/generate.py

@@ -8388,15 +8388,6 @@ class PythonParser(BaseParser):
             return f"[{elts}]"
         return "Complex"
 
-    def _get_args_info(self, args_node):
-        args_list = []
-        for arg in args_node.args:
-            arg_str = arg.arg
-            if arg.annotation:
-                arg_str += f": {self._get_type_annotation(arg.annotation)}"
-            args_list.append(arg_str)
-        return args_list
-
     def _get_param_types(self, args_node):
         """Extract parameter types as a list for metadata storage."""
         param_types = []
@@ -8492,12 +8483,14 @@ class PythonParser(BaseParser):
             is_method = parent_id in self.class_ids
             node_type = "Method" if is_method else "Function"
 
-            args = self._get_args_info(node.args)
             param_types = self._get_param_types(node.args)
             return_type = (
-                self._get_type_annotation(node.returns) if node.returns else "None"
+                self._get_type_annotation(node.returns) if node.returns else ""
             )
-            signature = f"def {node.name}({', '.join(args)}) -> {return_type}"
+            keyword = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+            signature = f"{keyword} {node.name}({ast.unparse(node.args)})"
+            if node.returns:
+                signature += f" -> {ast.unparse(node.returns)}"
 
             self.builder.add_node(
                 func_id,
@@ -25440,16 +25433,19 @@ class CodeGraphBuilder:
             output_path: Path to write the graph JSON
             scip_index: Optional ScipIndex for type-aware resolution
         """
-        from descry._graph import CURRENT_SCHEMA
+        from descry._graph import CALL_RELATIONS, CURRENT_SCHEMA
 
         self.resolve_references(scip_index=scip_index)
-        in_degree = {}
+        # The number of its callers: those certain and those it is one of
+        # the candidates of
+        callers = {}
         for edge in self.edges:
-            t = edge["target"]
-            if t:
-                in_degree[t] = in_degree.get(t, 0) + 1
+            if edge["relation"] in CALL_RELATIONS:
+                candidates = edge.get("metadata", {}).get("candidates", ())
+                for target in (edge["target"], *candidates):
+                    callers.setdefault(target, set()).add(edge["source"])
         for node in self.nodes:
-            node["metadata"]["in_degree"] = in_degree.get(node["id"], 0)
+            node["metadata"]["in_degree"] = len(callers.get(node["id"], ()))
         # Atomic write: stream to a sibling tmp file then os.replace. A
         # concurrent reader (MCP prewarm, web `/api/health`, another CLI
         # invocation) that stats the destination mid-write would otherwise

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/git_history.py

@@ -1662,8 +1662,8 @@ class GitHistoryAnalyzer:
 
             # Show callers if requested
             if show_callers and self.querier:
-                sym_name = name.split(".")[-1]  # Get base name
-                callers = self.querier.get_callers(sym_name)
+                # The callers of this symbol, not of every one of its name
+                callers = self.querier.get_callers(node_id)
                 if callers:
                     caller_names = []
                     for caller_id in callers[:5]:
@@ -1742,8 +1742,7 @@ class GitHistoryAnalyzer:
             }
 
             if show_callers and self.querier:
-                sym_name = name.split(".")[-1]
-                caller_ids = self.querier.get_callers(sym_name)
+                caller_ids = self.querier.get_callers(node_id)
                 if caller_ids:
                     callers = []
                     for caller_id in caller_ids[:5]:

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/handlers.py

@@ -749,7 +749,9 @@ def format_search_result(
 
     score_str = f"[{score:.2f}] " if show_score else ""
     metrics_str = (
-        f"({token_count} toks, {in_degree} callers)" if token_count or in_degree else ""
+        f"({token_count} toks, {in_degree} caller{'' if in_degree == 1 else 's'})"
+        if token_count or in_degree
+        else ""
     )
 
     lines = [f"{score_str}[{node_type}] {name} | {location} {metrics_str}".rstrip()]
@@ -1050,17 +1052,7 @@ class DescryService:
         self._git_cache_lock = asyncio.Lock()
         self._dedup_cache_lock = asyncio.Lock()
 
-        self._graph_cache = {"mtime": 0, "nodes": 0, "edges": 0, "error": None}
-        self._querier_cache = {"mtime": 0, "instance": None, "error": None}
-        self._semantic_cache = {
-            "mtime": 0,
-            "instance": None,
-            "loading": False,
-            "error": None,
-        }
-        self._semantic_load = None
-        self._git_cache = {"analyzer": None, "graph_mtime": None}
-        self._dedup_cache: dict[str, tuple[float, str]] = {}
+        self.reset_caches()
         self._max_dedup_entries = 100
 
         # Index runs write the same cache directory, so one runs at a time
@@ -1095,6 +1087,7 @@ class DescryService:
                         "mtime": mtime,
                         "nodes": len(data.get("nodes", [])),
                         "edges": len(data.get("edges", [])),
+                        "languages": self._graph_languages(data),
                         "error": None,
                     }
                 # ValueError: invalid JSON or invalid UTF-8.
@@ -1105,9 +1098,24 @@ class DescryService:
                         "mtime": mtime,
                         "nodes": 0,
                         "edges": 0,
+                        "languages": [],
                         "error": str(e),
                     }
 
+    def _graph_languages(self, data) -> list[str]:
+        """The languages of the graph's nodes, as the `lang` search filter
+        names them and finds them: by the extension of the file a node is
+        in."""
+        if self._get_syntax_lang is None:
+            return []
+        paths = {
+            node["id"][5:].split("::")[0]
+            for node in data.get("nodes", [])
+            if node.get("id", "").startswith("FILE:")
+        }
+        langs = {self._get_syntax_lang(p, self.config.syntax_lang_map) for p in paths}
+        return sorted(langs - {""})
+
     async def _get_querier(self):
         """The cached GraphQuerier; None if the graph is missing or unloadable."""
         if self._GraphQuerier is None:
@@ -1174,17 +1182,24 @@ class DescryService:
             self._dedup_cache[content_hash] = (graph_mtime, node_id)
 
     def reset_caches(self):
-        """Reset all cached instances. Call after reindex."""
-        self._graph_cache = {"mtime": 0, "nodes": 0, "edges": 0, "error": None}
+        """Reset all cached instances. Called on construction and after a
+        reindex."""
+        self._graph_cache = {
+            "mtime": 0,
+            "nodes": 0,
+            "edges": 0,
+            "languages": [],
+            "error": None,
+        }
         self._querier_cache = {"mtime": 0, "instance": None, "error": None}
         self._semantic_cache = {
             "mtime": 0,
             "instance": None,
-            "loading": False,
+            "load": None,
             "error": None,
         }
         self._git_cache = {"analyzer": None, "graph_mtime": None}
-        self._dedup_cache = {}
+        self._dedup_cache: dict[str, tuple[float, str]] = {}
         # The module-level file-content cache in query.py is keyed on mtime,
         # so it self-invalidates after an edit; but a reindex can shift file
         # contents even without an mtime bump (copies, git checkouts). Clear
@@ -1229,55 +1244,93 @@ class DescryService:
             source_root=str(self.config.project_root),
         )
 
+    def _start_semantic_load(self, cache, build):
+        """Run ``build`` in a thread as the load of ``cache``, which holds
+        what it builds, or the error it raises, as of the graph it began
+        on. Called holding the lock; returns the task."""
+        mtime = self._graph_mtime() or 0
+
+        async def load():
+            try:
+                # No timeout: the thread cannot be stopped, so a load given
+                # up on would go on while another started.
+                searcher = await asyncio.to_thread(build)
+                async with self._semantic_cache_lock:
+                    cache.update(mtime=mtime, instance=searcher, error=None)
+                return searcher
+            except Exception as e:  # noqa: BLE001 — boundary over sentence-transformers/torch model load; error is cached and logged
+                async with self._semantic_cache_lock:
+                    cache["error"] = str(e)
+                logger.warning(f"Embeddings load failed: {e}")
+                return None
+            finally:
+                async with self._semantic_cache_lock:
+                    cache["load"] = None
+
+        cache["load"] = asyncio.create_task(load())
+        return cache["load"]
+
     async def _load_embeddings_background(self):
+        """Load the searcher and its model, so the first search pays for
+        neither."""
+
+        def build():
+            searcher = self._new_searcher()
+            # On a warm cache the constructor never touches the model.
+            searcher.ensure_model()
+            return searcher
+
         async with self._semantic_cache_lock:
-            # A reindex replaces the cache, so a load writes only to its own.
             cache = self._semantic_cache
-            if cache["instance"] is not None or cache["loading"]:
+            if cache["instance"] is not None:
                 return
-            cache["loading"] = True
-            mtime = self._graph_mtime() or 0
-
-        try:
-
-            def load_sync():
-                searcher = self._new_searcher()
-                # On a warm cache the constructor never touches the model, so
-                # without this the pre-warm reports "ready" while the first
-                # real query still pays the full model load.
+            load = cache["load"] or self._start_semantic_load(cache, build)
+        if await asyncio.shield(load) is not None:
+            logger.info("Pre-warm: embeddings ready")
+
+    async def _load_indexed_embeddings(self, model_was_loaded):
+        """Load the embeddings of a graph just indexed, and the model where
+        it was loaded before; returns the line on them for the index's
+        summary, empty without embeddings."""
+        if not (
+            self._semantic_available
+            and self._SemanticSearcher
+            and self.config.graph_path.exists()
+        ):
+            return ""
+        logger.info("Loading embeddings for semantic search...")
+
+        def build():
+            # The child process has just embedded this graph and cached the
+            # vectors under a key derived from the graph's content, so this
+            # loads them. It encodes only when the child could not, since no
+            # cache then matches.
+            searcher = self._new_searcher()
+            # Loading from cache never touches the model. A server that had
+            # it loaded keeps it loaded, so the first search after a reindex
+            # does not pay for the load; a one-shot `descry index` skips it.
+            if model_was_loaded:
                 searcher.ensure_model()
-                return searcher
+            return searcher
 
-            # No timeout: the thread cannot be stopped, so a load given up on
-            # would go on building the cache while a search started another.
-            searcher = await asyncio.to_thread(load_sync)
-
-            async with self._semantic_cache_lock:
-                cache["mtime"] = mtime
-                cache["instance"] = searcher
-                cache["error"] = None
-                logger.info("Pre-warm: embeddings ready")
-        except Exception as e:  # noqa: BLE001 — boundary over sentence-transformers/torch model load; error is cached and logged
-            async with self._semantic_cache_lock:
-                cache["error"] = str(e)
-            logger.warning(f"Pre-warm: embeddings failed: {e}")
-        finally:
-            async with self._semantic_cache_lock:
-                cache["loading"] = False
+        async with self._semantic_cache_lock:
+            cache = self._semantic_cache
+            load = cache["load"] or self._start_semantic_load(cache, build)
+        searcher = await asyncio.shield(load)
+        if searcher is None:
+            return f"Embeddings: Failed ({cache['error']})"
+        return f"Embeddings: {len(searcher.nodes):,} nodes indexed"
 
     async def _get_semantic_searcher(self):
         """Single-flight accessor for the semantic searcher.
 
-        Returns the cached SemanticSearcher, rebuilding if
-        codebase_graph.json mtime changed. Returns None if embeddings are
-        unavailable (module missing or disabled), if the graph file does
-        not exist, or while a load is not done.
-
-        Uses _semantic_cache_lock; construction runs in asyncio.to_thread so
-        the event loop is not blocked by model load. Callers that want to
-        surface an "embeddings loading" UX string should check
-        _semantic_cache["error"] when this returns None: it is the last
-        failed load's until a load succeeds.
+        Returns the cached SemanticSearcher, loading it again if
+        codebase_graph.json mtime changed, and waits up to
+        `embedding_timeout` for a load under way. Returns None if
+        embeddings are unavailable (module missing or disabled), if the
+        graph file does not exist, or while a load is not done; then
+        _semantic_cache["error"] is the last failed load's until a load
+        succeeds.
         """
         if not self._semantic_available or self._SemanticSearcher is None:
             return None
@@ -1289,34 +1342,10 @@ class DescryService:
             cache = self._semantic_cache
             if cache["instance"] is not None and cache["mtime"] == mtime:
                 return cache["instance"]
-            if cache["loading"]:
-                return None
-            cache["loading"] = True
-
-        async def load():
-            try:
-                searcher = await asyncio.to_thread(self._new_searcher)
-                async with self._semantic_cache_lock:
-                    cache["mtime"] = mtime
-                    cache["instance"] = searcher
-                    cache["error"] = None
-                return searcher
-            except Exception as e:  # noqa: BLE001 — boundary over sentence-transformers/torch model load; error is cached and returned
-                async with self._semantic_cache_lock:
-                    cache["error"] = str(e)
-                logger.warning(f"Embeddings load failed: {e}")
-                return None
-            finally:
-                async with self._semantic_cache_lock:
-                    cache["loading"] = False
-
-        # The thread cannot be stopped: a load not done in time goes on and
-        # caches what it builds, and a search meanwhile is told it is loading.
-        self._semantic_load = asyncio.create_task(load())
+            load = cache["load"] or self._start_semantic_load(cache, self._new_searcher)
         try:
             return await asyncio.wait_for(
-                asyncio.shield(self._semantic_load),
-                timeout=self.config.embedding_timeout,
+                asyncio.shield(load), timeout=self.config.embedding_timeout
             )
         except TimeoutError:
             logger.warning(
@@ -1394,7 +1423,9 @@ class DescryService:
             health["features"]["embeddings"] = (
                 self._semantic_cache["instance"] is not None
             )
-            health["features"]["embeddings_loading"] = self._semantic_cache["loading"]
+            health["features"]["embeddings_loading"] = (
+                self._semantic_cache["load"] is not None
+            )
             health["features"]["embeddings_error"] = self._semantic_cache.get("error")
 
         if not self._semantic_available:
@@ -1439,6 +1470,7 @@ class DescryService:
             "age_hours": round(age_hours, 2),
             "nodes": self._graph_cache["nodes"],
             "edges": self._graph_cache["edges"],
+            "languages": self._graph_cache["languages"],
             "stale": age_hours > self.config.max_stale_hours,
             "error": self._graph_cache["error"],
         }
@@ -1665,56 +1697,8 @@ class DescryService:
                                 f"\nSCIP: {len(scip_files)} project(s) indexed"
                             )
 
-                embeddings_status = ""
-                if (
-                    self._semantic_available
-                    and self._SemanticSearcher
-                    and self.config.graph_path.exists()
-                ):
-                    try:
-                        # Reset the cache, then construct in a thread so the
-                        # event loop is not blocked.
-                        async with self._semantic_cache_lock:
-                            cache = self._semantic_cache = {
-                                "mtime": 0,
-                                "instance": None,
-                                "loading": True,
-                                "error": None,
-                            }
-                        logger.info("Generating embeddings for semantic search...")
-                        mtime = self._graph_mtime() or 0
-
-                        def _build_searcher():
-                            # The child process has just embedded this graph
-                            # and cached the vectors under a key derived from
-                            # the graph's content, so this loads them. It
-                            # encodes only when the child could not, since no
-                            # cache then matches.
-                            searcher = self._new_searcher()
-                            # Loading from cache never touches the model. A
-                            # server that had it loaded keeps it loaded, so
-                            # the first search after a reindex does not pay
-                            # for the load; a one-shot `descry index` skips it.
-                            if model_was_loaded:
-                                searcher.ensure_model()
-                            return searcher
-
-                        searcher = await asyncio.to_thread(_build_searcher)
-                        # Seed the cache with the freshly-built instance so
-                        # the next search() call reuses it.
-                        async with self._semantic_cache_lock:
-                            cache["mtime"] = mtime
-                            cache["instance"] = searcher
-                        embeddings_status = (
-                            f"\nEmbeddings: {len(searcher.nodes):,} nodes indexed"
-                        )
-                    except Exception as e:  # noqa: BLE001 — boundary over sentence-transformers/torch; reported in the index summary
-                        embeddings_status = f"\nEmbeddings: Failed ({e})"
-                        logger.warning(f"Embeddings generation failed: {e}")
-                    finally:
-                        async with self._semantic_cache_lock:
-                            cache["loading"] = False
-
+                embeddings = await self._load_indexed_embeddings(model_was_loaded)
+                embeddings_status = f"\n{embeddings}" if embeddings else ""
                 return f"Index complete.{scip_status}{embeddings_status}\n{output}"
             else:
                 return ServiceError(f"Index failed:\n{stderr}")
@@ -2584,16 +2568,8 @@ class DescryService:
                 return
 
             self.reset_caches()
-            # The child has cached this graph's vectors, so this loads them.
-            searcher = await self._get_semantic_searcher()
-            if searcher is not None:
-                line = f"Embeddings: {len(searcher.nodes):,} nodes indexed"
-                if model_was_loaded:
-                    try:
-                        await asyncio.to_thread(searcher.ensure_model)
-                    except Exception as e:  # noqa: BLE001 — boundary over sentence-transformers/torch; reported in the stream
-                        line = f"Embeddings: Failed ({e})"
-                yield {"type": "output", "line": line}
+            if embeddings := await self._load_indexed_embeddings(model_was_loaded):
+                yield {"type": "output", "line": embeddings}
             yield {"type": "done", "success": True, "message": "Index complete."}
         finally:
             self._index_lock.release()
@@ -2619,9 +2595,8 @@ class DescryService:
         if not results:
             trait_filter = f" for trait '{trait_name}'" if trait_name else ""
             return (
-                f"No trait implementations found for method '{method}'{trait_filter}.\n\n"
-                f"Note: trait_impl metadata is only available for recently indexed code. "
-                f"Run descry index to regenerate the graph with this metadata."
+                f"No trait implementations found for method '{method}'{trait_filter}. "
+                "Trait implementations are recorded for Rust code only."
             )
 
         by_trait = defaultdict(list)

{descry_codegraph-0.3.0 → descry_codegraph-0.3.1}/src/descry/mcp_server.py

@@ -218,7 +218,7 @@ async def descry_context(
     head_lines: int | None = None,
     max_output_tokens: int | None = None,
 ) -> str:
-    """Get full context for a symbol: source code, callers, callees, tests (~500+ tokens). Use brief=true (~50 tokens) to quickly verify a symbol before fetching full context. Options: full=true (no truncation), expand_callees=true (inline dependencies), head_lines=N (preview first N lines)."""
+    """Get full context for a symbol: source code, callers, callees, tests (~500+ tokens). Use brief=true (~50 tokens) to quickly verify a symbol before fetching full context. Options: full=true (no truncation), expand_callees=true (inline dependencies), head_lines=N (preview first N lines). node_id takes a node ID or a symbol name."""
     return _fenced(
         await _svc().context(
             node_id,
@@ -281,7 +281,7 @@ async def descry_structure(filename: str) -> str:
 
 @mcp.tool()
 async def descry_flatten(class_node_id: str) -> str:
-    """Show the effective API of a class including inherited methods. Use for understanding class hierarchies in OOP codebases."""
+    """Show the effective API of a class including inherited methods. Use for understanding class hierarchies in OOP codebases. class_node_id takes a node ID or a class name."""
     return _fenced(await _svc().flatten(class_node_id))
 
 
@@ -308,7 +308,7 @@ async def descry_quick(name: str, full: bool = False, brief: bool = False) -> st
 
 @mcp.tool()
 async def descry_impls(method: str, trait_name: str | None = None) -> str:
-    """Find all implementations of a trait method across the codebase. Use when you know a trait method name (e.g., 'from_request_parts') but need to find which types implement it. Optionally filter by trait name."""
+    """Find all implementations of a Rust trait method across the codebase. Use when you know a trait method name (e.g., 'from_request_parts') but need to find which types implement it. Optionally filter by trait name."""
     return _fenced(await _svc().impls(method, trait_name))