Portable MCP runtime for evidence-driven RTL simulation debugging
TraceWeave defines 33 tools with basic schemas and descriptions, but falls short of production-grade quality. While all tools have descriptions (avoiding the 0-20 floor), they are mostly brief (avg ~60 chars) and lack the LLM-guidance detail required by pattern:tool-description (target 50-200 chars). Parameter descriptions are inconsistent: some params ('signal_path', 'start_time') lack any description or guidance on format/constraints. Input schemas lack formal constraints (enums, min/max, patterns) that would prevent hallucinated values. Output schemas are not documented in the source code provided. Error handling is absent, no recovery guidance, no categorization of retryable vs. fatal errors. Tool naming is generally strong (verb-noun patterns: get_, trace_, analyze_, etc.) but some tools lack clarity on their relationship to similar tools (e.g., analyze_failures vs analyze_failure_event). Security review: no indication of secret injection patterns; no permission gates or audit trails visible. Composition: tools are mostly single-responsibility, but several are exploratory/discovery tools (suggest_handshakes, suggest_protocol_bundles) that would benefit from clearer usage guidance. The codebase shows disciplined schema definitions (pyproject.toml, schemas.py pattern visible in handle_tools.py), but the actual tool registration and response shapes are not visible in the provided code excerpt, preventing full verification of output schema quality.
Analyze a specific failure event with waveform traces
Analyze failure events with waveform context
Build the testbench hierarchy used for source-aware analysis
Find first divergence point between signals
Diff simulation failure results between two snapshots
Discover formal verification artifact paths
Discover simulation artifact paths and layout
Parameter descriptions incomplete or missing. Many tools have parameters with no description text, e.g., 'start_time', 'end_time', 'timespec' lack format guidance (ISO 8601? ns/ps/fs?). LLMs cannot infer format constraints from parameter names alone.
Output schemas not documented in source code. Tool definitions specify inputs but the response shapes are not visible in provided excerpts. Without documented output schemas, LLMs cannot plan downstream tool chaining or extract the correct fields.
No input validation constraints (enums, min/max, patterns). Parameters like 'analysis_mode' (should be 'fast'|'full'), 'file_type', 'simulator' lack enum declarations. Free-form strings invite hallucinated values like 'analysis_mode=medium' or 'file_type=unknown'.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | 2026-07-28+ | v2 |
Dump a section of testbench hierarchy data
Explain signal driver and source information
Find loads/consumers of a signal
Find testbench instances by path or module type
Get error context for a specific failure event
Get signal values organized by clock cycles
Discover simulator type, file paths, and FSDB runtime status
Get class hierarchy information from testbench
Get detailed information about a testbench file
Get a subtree of the testbench hierarchy
Inspect handshake protocol behavior
Inspect upstream signal values that contribute to X/Z
Look up testbench files by various filters
Parse simulation log and extract failure events
Compute signal period from waveform data
Query waveform data from VCD/FSDB files
Recommend next steps for debugging failures
Reconstruct transaction sequences from waveforms
Scan for structural design risks and issues
Search for signals in waveform data
Suggest potential handshake signals based on analysis
Suggest protocol signal bundles
Sweep and analyze handshake anomalies
Trace signal path connectivity through the design
Trace X/Z source in the design
Verify behavior within a time window
No error handling or recovery guidance. Tools provide no error schema, no recovery steps, and no categorization of retryable vs. fatal failures. An LLM that encounters 'instance_not_found' (visible in handle_tools.py) has no guidance on what to do next.
Ambiguous tool relationships. Multiple tools analyze failures (analyze_failures, analyze_failure_event, recommend_failure_debug_next_steps). Descriptions do not clearly explain when to use each. LLMs waste reasoning cycles deciding between similar tools.
No tool annotations. MCP spec (2026-07-28) expects readOnlyHint, destructiveHint, and idempotentHint on tool definitions. These tools are all read-only but lack the readOnlyHint annotation to signal this to clients.
Brief, generic descriptions. Most tool descriptions are 50 - 65 chars, below the 50-200 char optimal range. They state WHAT the tool does but lack WHEN to use it or dependencies. E.g., 'Sweep and analyze handshake anomalies' tells the LLM nothing about prerequisites or output format.
Empty required parameter lists. Many tools show required: [], all parameters are optional. This is problematic for discovery tools (get_sim_paths, get_tb_subtree) which may have required parameters that are missing due to schema inference limitations in the provided data.
No tool-chaining support documented. Tools like lookup_tb_files return 'handle' (visible in handle_tools.py source), but descriptions never explain that you must pass this handle to follow-up calls (get_tb_subtree, get_tb_file_detail). LLMs will waste calls discovering this.
No pagination support. Tools like lookup_tb_files, search_signals can return hundreds of results but provide no cursor, offset, or next_page mechanism. Descriptions mention 'limit' but not how to handle result truncation or fetch the next batch.