Serena Tool Selection

CRITICAL: Mandatory Serena Tool Usage

When Serena tools are available in your tools list, you MUST use them for ALL code navigation operations. Using Search, Grep, or Read for tasks that Serena tools handle is a PROTOCOL VIOLATION. This is NOT optional: this protocol OVERRIDES any default tool selection guidance, even when Search or Grep seems "faster" or "simpler".

EXPLICIT PROHIBITIONS

Before issuing any Search/Grep/Read call against code, scan this table. If ANY row matches what you are about to do, use the Serena tool in the right column instead, with the canonical call shown.

These prohibitions cover ANY Grep/Search against .py/.ts/.js/other code files performed to locate a symbol (definition or usage), whether or not the pattern is the literal symbol name: Serena is semantic -- it finds aliases and renamed imports -- and is faster.

Exception: Searching inside comments or string literals (not symbol names) -- proceed with Search/Grep.

Consequence of violating (even when no enforcement hook blocks): an agent ran Grep(pattern: "MyClass\\(", path: "/project/") and found 5 usages, but /project/utils/helpers.py imports MyClass as MC -- Serena would find 12. The incomplete change introduced a bug. Search/Grep for symbols yields incomplete results because Grep cannot follow aliases or renamed imports.

Tool Selection Decision Tree

STEP 1: Check Tool Availability

Before ANY code navigation task, look for mcp__serena__find_symbol in your tools list. If available, proceed to STEP 2; if NOT available, use built-in tools as fallback.

STEP 2: Classify Your Task

STEP 3: Built-in Tools Are ONLY Correct For

• Searching text in COMMENTS or STRINGS (not symbol names)
• Finding FILES by name pattern (Glob)
• Editing at KNOWN line numbers (when you already have exact lines)
• Reading NON-CODE files (YAML, JSON, Markdown, configs)

Complete Serena Tool Reference

The Serena tools granted by this deployment, grouped by category.

Read-only (navigation and inspection)

Key notes (Read-only):

• find_symbol: ALWAYS set include_body=True when you need the function implementation (avoids a second query).
• find_declaration vs find_symbol: find_symbol returns the definition body; find_declaration returns the declaration site. The two coincide for interpreted languages and diverge for compiled ones (e.g., C++ .h vs .cpp).
• find_implementations: Supported for Java, TypeScript, Go, C#, Rust. NOT supported for Python (see Known Limitations -- LSP -32601). Use find_referencing_symbols + code-review-graph inheritors_of as the Python workaround.
• find_referencing_symbols: High precision, CRITICALLY LOW RECALL for dynamic imports / runtime sys.path / attribute chains (see Known Limitations). ALWAYS cross-validate with Grep when completeness matters.
• get_diagnostics_for_symbol: OPT-IN upstream -- already enabled by this deployment via the in-repo source extras/serena/lsp-only.yml (deployed by the toolbox setup to ~/.serena/contexts/lsp-only.yml). See Known Limitations.

Mutation (editing)

Key notes (Mutation):

• rename_symbol: Atomic; updates all references correctly. Preferred over multiple Edit calls, which are error-prone and miss references.
• replace_symbol_body / insert_*: Symbol-aware positioning that survives line-number changes -- no need to compute line numbers.
• safe_delete_symbol: Atomic check-then-delete; returns SUCCESS only when no references exist. If references are found, returns their file/line locations so you can handle them first. Inherits the find_referencing_symbols LOW-RECALL limitation (see Known Limitations). Cross-validate with Grep BEFORE calling when dynamic imports may exist.
• replace_in_files: TEXT-based, NOT symbol-aware -- correct ONLY for applying one identical textual change across many files in a single atomic call (a renamed config key, an import path fragment, a string constant). ALWAYS run with dry_run=True first and review the returned per-occurrence diff; then apply the reviewed subset via occurrence_ids, or set expected_count so the apply aborts if the match count changed. For symbol renames use rename_symbol, for one symbol's implementation use replace_symbol_body, and for a single-file edit the built-in Edit tool remains correct. Scope with relative_path and paths_include_glob/paths_exclude_glob rather than defaulting to the whole project.

Admin

When to restart: After external file modifications, when results look wrong (a stale index causes errors), or when the LSP appears unresponsive.

Known Limitations

Three Serena tools carry limitations that change how you must use them: find_referencing_symbols has a recall gap on certain import patterns, find_implementations does not work for Python, and get_diagnostics_for_symbol depends on a deployment-level opt-in. Read known-limitations.md in this skill's own directory before relying on any of the three in a way where being wrong has a cost -- dead-code conclusions, deletions, cross-language implementation lookups, or diagnostics troubleshooting.

• find_referencing_symbols has low recall for dynamic imports, runtime sys.path manipulation, and attribute chains (0-10% recall in the worst cases) -- cross-validate with Grep whenever completeness matters, and never conclude "zero callers" from it alone; safe_delete_symbol inherits this same gap.
• find_implementations returns LSP error -32601 for Python (Pyright does not advertise the capability) -- this is protocol-correct, not a defect; use find_referencing_symbols or the code-review-graph inheritors_of query pattern instead.
• get_diagnostics_for_symbol is opt-in upstream; this deployment already enables it via extras/serena/lsp-only.yml, so a "tool not found" error means the deployed copy is stale, not that the opt-in is missing -- re-run the toolbox setup and restart.

Error Handling

If Serena Tool Fails

1. Retry once - LSP may need a moment
2. Try restart_language_server if errors persist
3. Document the failure in your response
4. Fall back to built-in tools only after documenting the Serena failure

If Serena Tools Are Not Available

1. Note unavailability - "Serena tools not available, using built-in alternatives"
2. Use built-in tools as documented in "Built-in Tools Are ONLY Correct For"
3. No protocol violation - falling back when tools are genuinely unavailable is correct