fw-context-mcp

Overview Schema Source Related Servers Discussions Admin

find_hotspots

Rank C/C++ functions by caller count to reveal call-graph hotspots for refactoring, optimization, or extra testing.

Instructions

Find the most-called C/C++ functions ranked by caller count — libclang call-graph hotspot detection. Identifies functions with the most architectural weight — good targets for refactoring, optimization, or extra testing. Text-based search cannot aggregate caller statistics across the full call graph.

Use for high-level impact assessment: changing a hotspot affects many call sites. The result tells you which functions carry the most "architectural weight" across the entire codebase.

By default, SDK/vendor paths are auto-excluded so hotspots reflect project code. Use project_only=False to see all results including vendor code.

For the callers of a specific hotspot, follow up with find_callers or find_all_callers_recursive.

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: Number of top-called functions per page (default 20, max 50). offset: Skip this many results. Reads further down the ranking; the page notice names the offset to use. project_only: When True (default), filters to is_project = 1 symbols so hotspots reflect project code. exclude_paths: Additional LIKE patterns to exclude (user-supplied tool parameter). E.g. ['lib/%']. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.

Returns: The page notice first — total, offset, shown, more — then a dict per function with: name, qualified_name, kind, signature, file (str — absolute), line, caller_count (int — number of call and indirect references to it).

Never empty: one dict with ``error`` or ``info`` replaces an empty
result.  Check both keys first.

Input Schema

Name	Required	Description
`image`	No	Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it.
`limit`	No	Number of top-called functions per page (default 20, max 50).
`offset`	No	Skip this many results. Reads further down the ranking.
`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	Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build.
`project_only`	No	When True (default), auto-excludes SDK/vendor paths so hotspots reflect project code.
`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	LIKE patterns on the project-relative file path to exclude, on top of project_only. E.g. ['lib/%'].

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.32.1Oct 19, 2026

changedInput schema / properties / exclude_paths / description

Previous value: -"Additional LIKE patterns to exclude. Merged with defaults. E.g. ['lib/%']."New value: +"LIKE patterns on the project-relative file path to exclude, on top of project_only. E.g. ['lib/%']."

changedInput schema / properties / image / description

Previous value: -"Sysbuild image within the variant. Required when the variant holds several: each image is a separate program."New value: +"Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it."

changedInput schema / properties / variant / description

Previous value: -"Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build."New value: +"Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build."

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: -"Number of top-called functions to return (default 20)."New value: +"Number of top-called functions per page (default 20, max 50)."

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

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Skip this many results. Reads further down the ranking.",
+  "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"
+}

Changed2 schema fields changedv0.5.0Jun 19, 2026

addedInput schema / properties / exclude_paths

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Additional LIKE patterns to exclude. Merged with defaults. E.g. ['lib/%'].",
+  "title": "Exclude Paths"
+}

addedInput schema / properties / project_only

Added value: +{
+  "default": true,
+  "description": "When True (default), auto-excludes SDK/vendor paths so hotspots reflect project code.",
+  "title": "Project Only",
+  "type": "boolean"
+}

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?

No annotations are provided, so the description carries the full burden and does so: it declares the tool read-only with no side effects, discloses the prerequisite reference index ('refs on by default'), documents the default SDK/vendor auto-exclusion and how project_only=False overrides it, and warns that results are never empty but may contain error/info keys to check first.

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?

Well structured and front-loaded: purpose, then when-to-use, then behavior, then args, then returns. Slightly padded by repetition of the 'architectural weight' framing, which is used twice, but no sentence is pure noise.

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?

Given 8 all-optional parameters, a prerequisite index, and a multi-build variant/image selection model, the description covers everything an agent needs to call it correctly, plus pagination and the error/info fallback contract. Nothing material is 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 already 100%, so the baseline is 3; the description still adds value by clarifying cross-parameter intent — project vs project_root as mutually exclusive alternatives ('give one of the two, not both') and offset semantics tied to the page notice 'the offset to use'. It does not add format or syntax detail beyond what the schema already supplies.

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?

States a specific verb and resource ('find the most-called C/C++ functions ranked by caller count') with implementation detail (libclang call-graph), and explicitly contrasts itself with sibling lookups ('For the callers of a specific hotspot, follow up with find_callers'). An agent can distinguish it from find_callers/find_all_callers_recursive without opening any schema.

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?

Gives explicit when-to-use ('Use for high-level impact assessment: changing a hotspot affects many call sites'), names the alternatives for the natural follow-up question, and states the capability boundary ('Text-based search cannot aggregate caller statistics across the full call graph').

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