CodeSentinel — AI-powered codebase health agent
Scored across 7 tools
Most tools have clearly distinct purposes: analyze_coupling, analyze_dead_code, detect_circular_deps, and detect_architectural_drift each target different code health aspects. The only potential overlap is full_health_scan, which runs all analyses, but it is distinct as an aggregator. check_mcp_health is completely different but clearly named.
The naming uses a mix of verbs: 'analyze_', 'detect_', 'check_', 'explain_', 'full_'. While all are snake_case and readable, the verb styles are inconsistent (analyze vs detect vs check). The convention is not uniform, making it a 3.
Seven tools is well-scoped for a code health analysis server. Each tool adds value, and the count is neither too thin nor too heavy.
The server covers key analyses: coupling, dead code, circular deps, architectural drift, and a full scan. explain_finding and check_mcp_health add extra utility. However, there is no tool for configuration or custom rule management, which could be a minor gap, but core coverage is strong.
Analyze coupling metrics across the codebase. Identifies modules with high fan-out (too many dependencies) and tightly coupled clusters.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | Path or URL to the repository | |
| fan_out_threshold | No | Fan-out threshold for flagging modules |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full transparency burden. It discloses what the tool identifies (high fan-out modules, tightly coupled clusters) but does not state whether it modifies anything, what permissions are needed, or how results are returned. The verb 'Analyze' suggests a read-only operation, but this is inferred rather than explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and followed by concrete outputs. No filler or redundant phrases. The structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and key concepts but lacks explicit output formatting, usage context relative to siblings, and side-effect disclosure. Since there is no output schema, agents would benefit from a sentence describing the return value. Comparable to a minimum-viable description for a simple analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both repo_path and fan_out_threshold have descriptions in the input schema. The tool description adds contextual meaning (e.g., 'high fan-out' clarifies the threshold concept) but doesn't introduce new parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a distinct analysis task—coupling metrics—with concrete outputs: high fan-out modules and tightly coupled clusters. This differentiates it from siblings like detect_circular_deps (which focuses on cycles) or analyze_dead_code (unused code). A clear verb and resource make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for coupling-focused analysis but offers no explicit when-to-use guidance or comparison to sibling analyzer tools. An agent could confuse it with detect_circular_deps or detect_architectural_drift without additional direction. There are no stated prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a codebase for dead code — functions, classes, and modules that are defined but never referenced. Returns findings with file paths, line numbers, severity, and fix suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | Path or URL to the repository to analyze | |
| include_suggestions | No | Whether to include fix suggestions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of explaining behavior. It does disclose that the tool returns findings with file paths, line numbers, severity, and fix suggestions, which implies a non-mutating analysis. However, it never explicitly says the tool is read-only or that it does not apply fixes, leaving some behavioral ambiguity for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It front-loads the core purpose, then adds a useful definition of dead code and the expected output structure without any filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema and no output schema, the description compensates well by explaining both what is detected and what the return findings contain. It is mostly complete, though a note about supported languages or explicit confirmation that the tool does not modify code would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters repo_path and include_suggestions are already documented. The description adds marginal value by mentioning 'fix suggestions,' which aligns with include_suggestions, but it does not elaborate on parameter-specific behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Analyze', the resource ('a codebase'), and the specific target (dead code: functions, classes, and modules defined but never referenced). This definition alone distinguishes the tool from siblings like analyze_coupling and detect_circular_deps, since each targets a different code quality concern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool when the need is to find unused definitions, and it specifies exactly what counts as dead code. It does not explicitly name alternatives or exclusions, but the scoped language makes the appropriate use case obvious relative to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Probe a remote MCP server: Streamable HTTP / SSE handshake (initialize + tools/list), a known-bad tools/call error-shape probe, and a Streamable HTTP diagnostic matrix (WRONG_METHOD, WRONG_ACCEPT, MISSING_SESSION, GET_VS_POST, SESSION_STICKY_MISMATCH). HTTP 200 is not treated as healthy.
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint | Yes | Remote MCP URL (Streamable HTTP or legacy SSE) | |
| transport | No | Transport probe mode. auto tries Streamable HTTP then legacy SSE | |
| timeout_ms | No | Per-request timeout in milliseconds | |
| baseline_hash | No | Previous canonical tools/list SHA-256 hex for drift alarms | |
| include_probes | No | Run silent-exception + Streamable HTTP diagnostics (default true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and discloses meaningful behavior: it performs a handshake, an error-shape probe, and a diagnostic matrix, and it explicitly warns that HTTP 200 is not treated as healthy. It does not state authentication requirements, side effects, or whether the probe is read-only, so some behavioral gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that puts the core action first and then lists the probes. It is dense but every part serves to specify behavior, with no obvious filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters with full schema coverage, no output schema, and no annotations, the description is fairly complete about what the tool does. It does not describe return values or safety profile, but the detailed probe list provides enough context for an agent to understand the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are documented in the input schema. The description adds no additional parameter meaning beyond what the schema already provides, making the baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Probe') and resource ('remote MCP server'), then enumerates exactly which handshake and diagnostic probes are performed. The subject matter is clearly distinct from the code-analysis sibling tools, so an agent can identify the tool's purpose without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description ('Probe a remote MCP server'), but there is no explicit guidance on when to use this tool versus alternatives such as full_health_scan. No when-not conditions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect architectural drift — violations of intended layer boundaries (e.g., UI importing from data layer, reverse dependencies).
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | Path or URL to the repository | |
| layers_config | No | JSON string defining layer patterns, e.g. {"ui": ["src/components/"], "data": ["src/db/"]} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It communicates the core behavior: detecting drift/violations of layer boundaries, and the examples suggest a non-destructive analysis. However, it doesn't disclose potential side effects, prerequisites (e.g., whether a local clone is required), or behavior when inputs are invalid or absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that defines the term with a dash and provides concrete examples. It is concise, contains no filler, and every phrase contributes to understanding. This is an ideal structure for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers both parameters, but the description leaves notable gaps: it does not clarify what happens when the optional parameters are omitted, how it relates to sibling detection tools, or whether any default configuration applies. These ambiguities prevent the definition from being fully complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both repo_path and layers_config, including an example JSON for layers_config. The description adds no parameter-specific meaning, but because the schema already documents both parameters thoroughly, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'Detect' and the resource 'architectural drift', defining it as violations of intended layer boundaries with concrete examples (UI importing from data layer, reverse dependencies). This is a specific and meaningful expression, not a tautology. It does not explicitly contrast with sibling tools like detect_circular_deps, so it does not earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by providing examples of architectural-drift violations, but it offers no explicit guidance on when to choose this tool over siblings like analyze_coupling or detect_circular_deps. There are no stated exclusions or alternative routing, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect circular dependencies between modules using DFS-based cycle detection. Returns cycles with involved files and impact assessment.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | Path or URL to the repository |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the algorithm (DFS-based detection) and what it returns, but it does not explicitly state whether the operation is read-only, what repository states are valid, or any limits or side effects. For an analysis tool this is acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that front-loads the action and resource, then clearly states the output. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers the key context well: what it detects, how it detects, and what it returns (cycles with files and impact assessment). It could be improved with notes on prerequisites or edge cases, but nothing essential is missing for a basic call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter repo_path is already fully described in the schema as 'Path or URL to the repository', giving 100% schema description coverage. The description adds no additional parameter-level details, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Detect') and resource ('circular dependencies between modules'), and adds the method ('DFS-based cycle detection'). This clearly differentiates it from siblings like analyze_coupling or detect_architectural_drift, which target different concerns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implicitly clear: use when you need to find circular dependencies among modules. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions, leaving the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a detailed explanation of a specific code health finding, including why it matters, potential risks, and detailed remediation steps.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_type | Yes | ||
| codebase_context | No | Additional context about the codebase (language, framework, etc.) | |
| finding_description | Yes | Description of the specific finding to explain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavior disclosure. It does communicate that the tool is a read-only explanation operation and summarizes the output content. It does not mention prerequisites, side effects, possible errors, or response structure, but for an information-retrieval tool this is acceptable though not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no filler. It front-loads the action ('Get a detailed explanation') and immediately states the key output components. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity explainer tool with no output schema, the description adequately covers the tool's purpose and expected return content, while the schema covers parameters. The main gap is the lack of explicit guidance on when to use this relative to the sibling analysis and detection tools, but that is not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for finding_description and codebase_context, and the enum documents finding_type. The description adds little to parameter understanding beyond framing the finding as 'specific.' With 67% schema coverage, the description does not need to compensate heavily, but it also does not enrich the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a detailed explanation of a specific code health finding and enumerates the content of that explanation (why it matters, risks, remediation). It is implicitly distinguished from the sibling detection/analysis tools, but it does not explicitly name them or contrast itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: the agent should use this tool when it has a specific finding to explain, likely after running one of the detection or analysis tools. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a complete codebase health scan: dead code, circular dependencies, coupling metrics, and architectural drift. Returns an overall health score (0-100) and prioritized findings.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | No | Path or URL to the repository |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool returns a score (0-100) and prioritized findings, and its 'scan' wording implies a read-only operation, so it is not misleading. However, it does not explicitly state that the scan is non-destructive, nor does it mention potential side effects of accepting a URL (e.g., cloning), runtime cost, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: the first front-loads the action and scope, the second states the return. Every phrase earns its place and there is no fluff or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the low parameter count, the description leaves critical gaps: repo_path is optional (required: 0) but the description does not say what happens when it is omitted; no output schema exists, so 'prioritized findings' remains vague; and the relationship to the specialized sibling tools is not stated, so an agent cannot tell whether it should call this tool or the individual ones for details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter repo_path, which is described as 'Path or URL to the repository'. The description adds no additional meaning about this parameter, staying at the baseline, and it does not clarify the parameter's optionality (required parameters: 0) or default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Run a complete codebase health scan'), enumerates the exact scan dimensions (dead code, circular dependencies, coupling metrics, architectural drift), and defines the output (health score 0-100 and prioritized findings). This clearly separates it from the specialized sibling tools by covering them all in one complete scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'complete' implies this is the aggregate tool to use when a broad health overview is needed, but the description never explicitly tells the agent when to prefer this over analyze_coupling, analyze_dead_code, etc., nor does it list any exclusions. Usage must be inferred from the listing of sub-analyses rather than stated guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_mcp_health1 field changedInput schema / properties / include_probesAdded value: +{
+ "description": "Run silent-exception + Streamable HTTP diagnostics (default true)",
+ "type": "boolean"
+}analyze_couplinganalyze_dead_codecheck_mcp_healthdetect_architectural_driftdetect_circular_depsexplain_findingfull_health_scan
Add one secure layer between your agents and this server.