fw-context-mcp

Overview Schema Source Related Servers Discussions Admin

find_dead_code

Find C/C++ functions defined but never called anywhere in the codebase, using libclang index analysis. Returns dead or possibly_dead status with reasons, and filters to project code by default.

Instructions

Find C/C++ functions that are defined but never called — libclang-powered dead code detection across the entire indexed codebase. Distinguishes called from uncalled symbols globally, not just within a single file — text-based search cannot determine whether a function is actually reachable.

What "dead" means: zero references in the index — no call, no function-pointer assignment, no indirect call site. This is a single-layer reference check, NOT a reachability analysis from the entry points (main, ISR, exported symbols): a function that only a second dead function calls still has a reference, thus this tool does not mark it. For transitive reachability, trace from your entry points with find_callees_recursive.

The status field splits the results:

"dead" — no reference at all. Likely unused.
"possibly_dead" — assigned to a function pointer (Phase 1 ref_kind="indirect"), but no call site through that pointer resolved (Phase 3). Unindexed code or a type-erased API can still call it. Treat it as uncertain, and check each hit with find_indirect_targets before you delete anything.

fw-context detects a constructor call through global/static object and member-field initialization as an implicit_construct reference. Known false positives remain: constructors from factories, ISRs, virtual method overrides, and weak-aliased symbols. Always verify before you delete.

project_only=True (default) excludes the SDK and vendor paths through the is_project column, which follows the vendor_paths and project_paths config. Set project_only=False to see the vendor results too.

Read-only. No side effects. Requires the reference index (fw-context index — refs on by default).

Args: project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results of one page (default 100, max 200). offset: Skip this many results. Reads the next page; the page notice names the offset to use. exclude_paths: Additional LIKE patterns to exclude (user-supplied tool parameter, not config). E.g. ['lib/%']. project_only: When True (default), filters to is_project = 1 symbols. Set False to see all results. variant: Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. image: Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.

Returns: list of dicts, each with: name, qualified_name, kind, signature, file (str — absolute), line, status ("dead" or "possibly_dead"), and reason (str — explains why the function is classified as dead or possibly dead).

Never empty: one dict with ``info`` replaces an empty result.
Check that key first.

Input Schema

TableJSON Schema

Name	Required	Description
`image`	No	Sysbuild image within the variant. Required when the variant holds several: each image is a separate program.
`limit`	No	Maximum results of one page (default 100, max 200).
`offset`	No	Skip this many results. Reads the next page of a long report.
`project`	No	Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both.
`variant`	No	Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build.
`project_only`	No	When True (default), auto-excludes SDK/vendor paths based on the detected build system and applies project config exclude_paths. Set False to see all results.
`project_root`	No	Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those.
`exclude_paths`	No	Additional LIKE patterns to exclude. Merged with defaults from config. E.g. ['lib/%'].

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.32.0Sep 17, 2026

changedInput schema / properties / image / description

Previous value: -"Sysbuild image name within the variant (multi-project). Omit for all images of the variant."New value: +"Sysbuild image within the variant. Required when the variant holds several: each image is a separate program."

changedInput schema / properties / limit / description

Previous value: -"Maximum results (default 100)."New value: +"Maximum results of one page (default 100, max 200)."

addedInput schema / properties / limit / minimum
```
Added value: +1
```

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Skip this many results. Reads the next page of a long report.",
+  "minimum": 0,
+  "title": "Offset",
+  "type": "integer"
+}

changedInput schema / properties / variant / description

Previous value: -"Build variant name (multi-project). Omit to use default_variant or fail-closed. Use '*' for all variants."New value: +"Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build."

Changed3 schema fields changedv0.30.0Sep 5, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / project

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both.",
+  "title": "Project"
+}

changedInput schema / properties / project_root / description

Previous value: -"Project root. Auto-detected if omitted."New value: +"Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those."

Changed2 schema fields changedv0.25.3Aug 16, 2026

addedInput schema / properties / image

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Sysbuild image name within the variant (multi-project). Omit for all images of the variant.",
+  "title": "Image"
+}

addedInput schema / properties / variant

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Build variant name (multi-project). Omit to use default_variant or fail-closed. Use '*' for all variants.",
+  "title": "Variant"
+}

Changed1 schema field changedv0.18.2Jul 10, 2026

changedInput schema / properties / project_only / description

Previous value: -"When True (default), auto-excludes SDK/vendor paths (mbed-os/%, .pio/%, zephyr/%, build/%) and applies project config exclude_paths. Set False to see all results."New value: +"When True (default), auto-excludes SDK/vendor paths based on the detected build system and applies project config exclude_paths. Set False to see all results."

Changed2 schema fields changedv0.5.0Jun 19, 2026

changedInput schema / properties / exclude_paths / description

Previous value: -"File path LIKE patterns to exclude. E.g. ['mbed-os/%', 'zephyr/%'] for SDK paths. No default — pass explicitly to filter vendor noise."New value: +"Additional LIKE patterns to exclude. Merged with defaults from config. E.g. ['lib/%']."

addedInput schema / properties / project_only

Added value: +{
+  "default": true,
+  "description": "When True (default), auto-excludes SDK/vendor paths (mbed-os/%, .pio/%, zephyr/%, build/%) and applies project config exclude_paths. Set False to see all results.",
+  "title": "Project Only",
+  "type": "boolean"
+}

Changed1 schema field changedv0.2.4Jun 18, 2026

addedInput schema / properties / exclude_paths

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "File path LIKE patterns to exclude. E.g. ['mbed-os/%', 'zephyr/%'] for SDK paths. No default — pass explicitly to filter vendor noise.",
+  "title": "Exclude Paths"
+}

First observedv0.1.0Jun 10, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and succeeds: it states 'Read-only. No side effects', requires the reference index, defines the two statuses, and discloses known false positives and the single-layer non-reachability limitation. This is far beyond what structured annotations would provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with bold headings, clear bullets, and front-loaded purpose. It is somewhat long and the Args section largely duplicates the input schema, but the tool is complex enough that the extra caveats and status semantics earn most of their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with no annotations, the description is remarkably complete: it covers output shape, the never-empty info replacement, prerequisites, read-only behavior, filtering semantics, pagination, and false positives. Nothing needed for safe invocation is materially missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds some genuinely useful clarifications beyond the schema: project_root and project are mutually exclusive, offset pagination references a page notice, and exclude_paths is a user-supplied parameter rather than config. These additions justify a small bump above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Find C/C++ functions that are defined but never called', and frames the tool as global, index-based dead code detection. It also distinguishes itself from text-based search and names related siblings like find_callees_recursive and find_indirect_targets, so an agent can select it correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool versus alternatives: for transitive reachability it should use find_callees_recursive, and for possibly_dead hits it should verify with find_indirect_targets. It also explains that text-based search cannot determine actual reachability, which is a strong when/why signal.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.