tzero-mcp

Diagnose and Self Heal System Runtime and Codebase Flaws

diagnose_and_heal_system

Diagnose workspace health and automatically repair Python syntax errors, broken virtualenv paths, missing imports, BOM artifacts, and stale bytecode caches, with optional dry-run previews.

Instructions

Diagnoses and automatically repairs environment misconfigurations, virtualenv breakages, syntax errors, missing standard library imports, UTF-8 BOM artifacts, and orphaned bytecode across the workspace, distinguishing from 'heal_hallucinated_code' which strictly corrects phantom AST symbols in code snippets by instead performing holistic system-level health diagnostics and autonomous multi-category file healing.

Parameters:

workspace_dir (str, optional, default='.'): Target repository root directory containing source code and environment configurations to diagnose.
auto_repair (bool, optional, default=True): When True, applies surgical AST syntax patches, BOM sanitization, and cache purges to disk.
dry_run (bool, optional, default=False): When True, evaluates diagnostics and previews repair diffs without modifying files on disk.

Behavior:

Mutability: Modifies files only when auto_repair=True and dry_run=False; otherwise strictly read-only.
Idempotency: Multiple sequential executions converge to a 100% clean state without regressions.
Performance & Latency: Scans and repairs 250+ files in <400ms using local standard library AST.
Resources: Consumes <50MB RAM; local file system operations only.
Privacy: 100% offline local processing; zero external network transmission.
Auth & Limits: Zero external credentials or API keys required; zero rate limits.
Error Handling: Continues diagnostic sweep across entire workspace if individual files contain unrecoverable binary corruption.

Usage Guidelines:

When to use: Use when diagnosing overall workspace health, repairing Python syntax breakages (missing colons, Python 2 print), resolving missing standard imports, fixing virtualenv paths, or purging stale cache bloat.
When NOT to use: Do not use for repairing hallucinated LLM method names in isolated code snippets (use 'heal_hallucinated_code' instead); do not use for static cyclomatic complexity code smell audits (use 'audit_code_quality' instead).

Returns: Formatted Markdown report detailing initial health score, detected defects, surgical patch actions, and final post-healing health score.

Input Schema

Name	Required	Description	Default
`dry_run`	No	Whether to preview repairs without writing to disk (default: False).
`auto_repair`	No	Whether to apply self-healing patches to disk (default: True).
`workspace_dir`	No	Target repository root directory (default: current directory).	.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv10.6.0Nov 6, 2026

TDQS

A4/5.0

Behavior2/5

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

The description discloses mutability conditions, error handling, performance, resource and auth profiles far beyond what the annotations state — genuinely useful for a mutating tool. However, it asserts 'Idempotency: Multiple sequential executions converge to a 100% clean state without regressions,' which directly conflicts with the supplied idempotentHint=false, and the 'strictly read-only' claim for the dry_run/auto_repair=False path sits uneasily with readOnlyHint=false. An agent relying on the idempotency claim could re-run expecting no side effects.

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 purpose and sibling differentiation are front-loaded, and the labeled sections (Behavior, Usage Guidelines, Returns) aid scanning. However, the 'Parameters:' block largely restates a 100% covered schema, and the performance/resource/privacy/auth bullet lines add bulk whose value is marginal for a local-only tool.

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?

With an output schema present and annotations supplied, the remaining burden is mutability, failure modes, and scope, all of which are covered (continues sweep on binary corruption, offline processing, no credentials). The one incomplete piece is the unresolved conflict between the claimed idempotency and the idempotentHint annotation.

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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: auto_repair is specified as applying 'surgical AST syntax patches, BOM sanitization, and cache purges to disk,' and dry_run as previewing 'repair diffs without modifying files on disk.' It also clarifies that workspace_dir must be a repository root containing source and environment configs, not an arbitrary path.

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 plus resource ('Diagnoses and automatically repairs...') and enumerates the exact defect categories it targets (virtualenv breakages, syntax errors, BOM artifacts, orphaned bytecode). It explicitly differentiates itself from the sibling 'heal_hallucinated_code' by contrasting snippet-level AST symbol repair with holistic system-level healing.

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?

Provides an explicit 'When to use' list of concrete triggers and a 'When NOT to use' list that names two alternatives ('heal_hallucinated_code' for snippet-level hallucinated symbols, 'audit_code_quality' for cyclomatic complexity audits). An agent can route between these three tools without opening any schema.

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