fw-context-mcp

Overview Schema Source Related Servers Discussions Admin

find_hotspots

Ranks C/C++ functions by caller count across the call graph to surface high-impact hotspots for refactoring, optimization, or 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: 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, caller_count (int — total number of call sites).

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	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	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 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	Additional LIKE patterns to exclude. Merged with defaults. 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: -"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.2/5.0

Behavior4/5

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

With no annotations, the description carries the full disclosure burden. It explicitly says 'Read-only. No side effects.', declares the reference index requirement, reveals the never-empty 'info' sentinel, and warns that one query answers for one build. These are substantive behavioral disclosures beyond the schema.

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 long but logically structured: purpose, usage, parameters, return format. It front-loads the main purpose and keeps related caveats in the parameter/return sections. Some repetition exists ('architectural weight' twice), but every block earns its place for a complex tool.

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 an 8-parameter tool with no annotations, this description is unusually complete: it covers prerequisites, defaults, output shape, the empty-result sentinel, build/variant specifics, and follow-up paths. An agent has everything needed to invoke it correctly.

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

Parameters3/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 mostly repeats schema text, adding minor context like the page-notice offset hint and the project/project_root mutual exclusivity. It confirms the schema but does not meaningfully extend parameter meaning.

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 the most-called C/C++ functions ranked by caller count' and names the mechanism (libclang call-graph hotspot detection). It clearly distinguishes this from Text-based search and from sibling tools like find_callers, making selection unambiguous.

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

Usage Guidelines4/5

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

It explicitly states the intended use ('high-level impact assessment'), notes that text search cannot aggregate caller stats, and gives concrete follow-up alternatives (find_callers, find_all_callers_recursive). It does not enumerate all negative cases for every sibling, but the usage context is clear and actionable.

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