Purpose: The primary tool for analyzing the impact boundary of a known change target. Outputs direct call sites, direct consumers, main propagation chains, risks, and suggested modification order. When to use: Use when you already know which symbol, field, interface contract, or file to change, and want to understand what will be affected before making the change. Best practice: Provide an explicit target; if you know the file containing the symbol, also provide the file parameter to speed up resolution. Frame the question as a concrete change, e.g. 'modify field X', 'change function signature of Y', 'what breaks if file Z is deleted'. Avoid: If the target is still ambiguous or you are choosing between multiple candidates, do not use impact as a substitute for the discovery step — use pce_query first to converge on the target. If you only want to view local implementation or exact definitions, impact is not necessary.

Purpose: Bind a target project and initialize the PCE runtime, building the index and navigation context required by query / impact / sync. When to use: Call this when entering a new project or the first time PCE is needed in a session. Do NOT call pce_query, pce_impact, pce_sync, or edit tools before pce_init succeeds. Best practice: Typically called once per session and awaited until success. Only call again when switching projects or retrying after a failure. Avoid: Do not use this as a code query tool; it establishes context but does not directly answer code questions.

Purpose: The primary tool for codebase navigation and understanding. Best suited for project-level understanding, architecture overviews, major module responsibilities, entry points, main call chains, candidate file scopes, and overall project/module comprehension. When to use: Use when the target location is unclear. When you do not know which file contains the information, need to understand what the project or a subsystem does, need a rough architecture or module-level picture, want to find entry points / main call chains / module responsibilities, or need to narrow down the search scope — use this tool first. Do NOT manually traverse directories, broadly inspect the repo, or batch-read files before trying pce_query. Best practice: Prefer describing your question in natural language rather than just giving exact identifiers. This tool is especially appropriate for questions like what the project does, how a subsystem is organized, where a feature lives, or which modules participate in a workflow. You can request file:line references, name_path, candidate file lists, call chain summaries, or results grouped by module. Avoid: When you already know the exact file or exact identifier and only need to view local implementation or do exact string matching, pce_query is not necessary. If the target is already clear and the task becomes 'what will be affected by changing it', switch to pce_impact instead.

Purpose: Return current service and project status, including initialization phase, index statistics, staging area, and warnings. When to use: Use when you need to confirm whether PCE is available, whether the index has been built, or to diagnose init / query / impact / sync issues. Best practice: Treat this as a diagnostic tool. When unsure whether to call init or sync first, check status. Avoid: Do not use this as a code understanding tool; it does not locate entry points, call chains, or impact boundaries.

Purpose: Synchronize Serena and PCE index state after codebase modifications, so subsequent query / impact calls work against the latest code. When to use: Use after completing a batch of code modifications, file deletions, renames, or structural changes. Best practice: Use this as a batch synchronization step; typically call once after completing a round of changes, rather than after every small edit. Avoid: Do not use this as a code understanding tool; it refreshes index state but does not explain code.