Skip to main content
Glama
aimasteracc

tree-sitter-analyzer

by aimasteracc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

health

Read-onlyIdempotent

Run project, file, or codebase health checks: grade quality, detect anti-patterns, dead code, routes, and dependency cycles to guide refactoring.

Instructions

Code-intelligence (codegraph-compatible) health and analysis facade. Covers codegraph_complexity_heatmap, codegraph_import_graph, codegraph_dependency_matrix, codegraph_dead_code, codegraph_overview, and project/file health metrics in one tool. Pick a capability via action:

  • action=project — overall project code-quality grade + per-file grade breakdown. Params: min_grade, max_files.

  • action=file — per-file health: complexity, duplication, style. Params: file_path (required), language.

  • action=scale — lines-of-code / complexity / size metrics. Params: file_path, file_paths, language, metrics_only, include_complexity, include_details, include_guidance.

  • action=patterns — anti-pattern detection by category and severity. Params: file_path (required), categories, severity_threshold.

  • action=heatmap — complexity heatmap ranked by file or function (codegraph_complexity_heatmap equivalent). Params: mode, file_path, function_name, language, directory, max_files.

  • action=imports — module import dependency graph (who imports whom, codegraph_import_graph equivalent). Params: mode, file_path, max_depth.

  • action=matrix — coupling matrix and top-k coupling ranks (codegraph_dependency_matrix equivalent). Params: mode, file_path, top_k, threshold.

  • action=dead — unreferenced functions / unused imports / unused variables (codegraph_dead_code equivalent). Params: mode, include_test_files, max_dead, max_imports, max_variables.

  • action=unreachable — statement-level unreachable code inside live functions. Params: mode (file|project), file_path, include_test_files, max_files.

  • action=middleware — framework middleware/interceptor chains. Params: mode (all|summary|lookup), url_prefix, framework.

  • action=routes — HTTP route discovery across framework conventions. Params: mode, url_pattern, file_path, framework.

  • action=overview — entry-points / hub files / dead-code summary (codegraph_overview equivalent). Params: max_entry_points, max_hubs, max_dead, max_coupled_files.

  • action=deps — dependency analysis (R5 multi-mode). Params: mode (summary|cycles|blast|file_deps), file_path. mode=summary: project-level dependency overview. mode=cycles: detect circular dependencies. mode=blast: blast-radius for a given file_path. mode=file_deps: file-level dependency details.

  • action=test_gap — untested symbol discovery ranked by cyclomatic complexity. Params: mode (summary|gaps|file), file_path, language, max_files, max_gaps, include_covered, output_format.

  • action=self — self-proprioception (RFC-0025 Layer 5): per-(tool, action) p50/p95 latency split by tier (cold/warm/cached), exact invocation counts, the in-process analysis-cache hit rate, and the on-disk AST-index state (.ast-cache/index.db) for THIS process. No params. Unmeasured values are null with status NO_OBSERVATIONS — never a fabricated 0.0.

  • action=refactor_queue — top-N prioritized refactor queue (RFC-0027 §L8): files ranked by (1 - health/100) * log(1 + churn_30d) * (dead_ratio + 0.1), each row carrying grade, weakest dimension, 30-day churn, dead-symbol count and a concrete action (split / delete dead / extract). Returns CHURN_UNAVAILABLE rather than a queue of zeros when the AST index has no churn to read. Params: top_n. For UML diagrams, call/dependency graph visualizations, and similarity analysis, use the viz facade instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNoAction sub-mode (e.g. summary|cycles).
limitNoMax results.
queryNoSearch query/pattern.
scopeNoAction discriminator (e.g. point|graph).
actionYesWhich capability to invoke. One of: dead, deps, file, heatmap, imports, matrix, middleware, overview, patterns, project, refactor_queue, routes, scale, self, test_gap, unreachable
symbolNoSymbol/function name.
languageNoLanguage hint (usually auto).
file_pathNoTarget file path.
function_nameNoFunction name (alias of symbol).
output_formatNoOutput format: JSON.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.30.0
    • changedInput schema / properties / action / description
      Previous value: -"Which capability to invoke. One of: dead, deps, file, heatmap, imports, matrix, overview, patterns, project, routes, scale, test_gap"New value: +"Which capability to invoke. One of: dead, deps, file, heatmap, imports, matrix, middleware, overview, patterns, project, refactor_queue, routes, scale, self, test_gap, unreachable"
    • changedInput schema / properties / action / enum
      Previous value: -[
-  "dead",
-  "deps",
-  "file",
-  "heatmap",
-  "imports",
-  "matrix",
-  "overview",
-  "patterns",
-  "project",
-  "routes",
-  "scale",
-  "test_gap"
-]New value: +[
+  "dead",
+  "deps",
+  "file",
+  "heatmap",
+  "imports",
+  "matrix",
+  "middleware",
+  "overview",
+  "patterns",
+  "project",
+  "refactor_queue",
+  "routes",
+  "scale",
+  "self",
+  "test_gap",
+  "unreachable"
+]
    • changedInput schema / properties / output_format / description
      Previous value: -"Output format (toon|json)."New value: +"Output format: JSON."
    • addedInput schema / properties / output_format / enum
      Added value: +[
+  "json"
+]
  2. First observedv1.23.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met; the description goes further and discloses non-obvious behaviors beyond the annotations: 'self' returns null with status NO_OBSERVATIONS rather than fabricated zeros, and refactor_queue returns CHURN_UNAVAILABLE rather than a queue of zeros when churn data is missing. These honesty-of-output behaviors are genuinely useful context an agent cannot get from annotations. It stops short of describing auth, rate limits, or return shapes for most actions, which is why it is not a 5.

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

Conciseness3/5

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

The facade summary is front-loaded and well organized, but the bulk is a long bulleted catalog where several actions (self, refactor_queue) interleave dense RFC references and behavioral caveats. It earns most of its length, but the sheer volume and uneven per-action param detail make it heavier than ideal for a single tool definition.

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

Completeness4/5

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

This is a very high-complexity dispatch tool (16 actions, 10 params, no output schema). The description covers nearly every action with intent and params, names the sibling to use for adjacent needs, and flags the two actions whose outputs can be unavailable. It is complete enough for correct invocation, though a few actions rely on the schema for their param lists and no output shapes are given (none can be, since no output schema exists).

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 schema documents each parameter type. The description adds real value by mapping which params apply to which action (e.g. min_grade/max_files for project, file_path+categories+severity_threshold for patterns, mode sub-values for deps) and by clarifying deps mode semantics (summary/cycles/blast/file_deps). This exceeds the 3 baseline, though it does not cover every param and some actions omit param lists.

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 compound resource ('Code-intelligence health and analysis facade') and enumerates exactly which capabilities it consolidates (heatmap, import graph, dependency matrix, dead code, overview), routing diagram/visualization work to the sibling 'viz' facade. An agent can tell this apart from 'project', 'structure', 'nav', and 'viz' 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?

It gives explicit when-to-use guidance for each of the 16 action values, ties each to its own param set, and explicitly excludes a class of work ('For UML diagrams, call/dependency graph visualizations, and similarity analysis, use the viz facade instead'). This is a textbook dispatch-tool routing contract.

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

Deploy Server

Other Tools