Tool Overview¶

Sentinel DV provides 28 MCP tools organized into categories for verification intelligence.

Tool Categories¶

🔍 Discovery Tools¶

Find and list verification artifacts with filtering and pagination.

Tool	Purpose	Key Filters
`runs.list`	List indexed runs	suite, status, time range, CI info
`tests.list`	List tests	run_id, framework, status, name pattern
`assertions.list`	List assertions	scope, protocol, tags
`coverage.list`	List coverage summaries	run_id, kind, scope

📊 Detail Tools¶

Get comprehensive information about specific items.

Tool	Purpose	Returns
`tests.get`	Get test details	Full TestCase with evidence
`tests.history`	Test outcomes over time	Status timeline + flaky hint
`tests.topology`	Get test topology	UVM hierarchy + interface bindings
`runs.get`	Get run details	Run identifier
`runs.summary`	Per-run rollup	Test counts, pass rate, slowest tests
`assertions.get`	Get assertion definition	AssertionInfo with intent

🔬 Analysis Tools¶

Analyze failures, assertions, and coverage.

Tool	Purpose	Key Features
`failures.list`	List failure events	Categorized, with evidence
`assertions.failures`	List assertion failures	Runtime failures linked to definitions
`coverage.summary`	Get coverage metrics	Bounded metrics with missed bins

📈 Regression Tools¶

Regression analytics and comparisons.

Tool	Purpose	Returns
`regressions.summary`	Regression summary	Pass rate + top failure signatures
`runs.diff`	Compare two runs	Structured diff with coverage deltas

🌊 Waveform Tools¶

Pre-computed summaries from *.wave.json and *.vcd (built-in VcdSummaryParser). No raw FSDB/WLF streaming to clients.

Tool	Purpose	Status
`wave.signals`	List signals; optional `start_time_ns` / `end_time_ns` window	Stable
`wave.summary`	Highlights and metadata; same time window	Stable

Full parameter reference: MCP tools reference.

MCP tool gallery (visual)¶

Auto-generated SVG cards show real request/response JSON for every tool (from the multi-project demo/ index):

Browse all 28 tools in the gallery — embedded screenshots + full JSON
Interactive HTML preview — open in a new tab

Regenerate after demo or API changes:

python scripts/generate_mcp_tool_gallery.py

🚀 v2.0.0 Tools¶

New in v2.0.0: job submission, live simulation monitoring, SVA formal status, seed replay, and coverage closure.

Tool	Purpose	Requires config
`runs.submit`	Generate simulator submit command	`submit.enabled: true`
`sim.status`	Live simulation progress	`adapters.live_sim: true`
`assertions.sva_status`	SVA/formal property status	—
`assertions.vacuity`	Vacuously-passing assertions	—
`tests.replay`	Seed-replay command for failing test	`submit.enabled: true`
`coverage.gaps`	Prioritized coverage closure guidance	—

🧠 v2.1.0 DV Intelligence Tools¶

New in v2.1.0: actionable intelligence tools that go beyond data reporting into automated DV decision support.

Tool	Purpose	Key Insight
`coverage.trend`	Coverage trajectory over time	Identifies stalled or regressing coverage
`runs.cross_sim`	Cross-simulator divergence detector	Finds tests that pass on one sim but fail on another
`tests.cluster`	Failure root-cause clustering	Groups failures by common signature for faster triage
`regression.health`	Composite DV readiness score	0–100 sign-off readiness with weighted sub-scores
`coverage.advisor`	SV constraint code generator	Protocol-aware snippets (AXI4, AHB, APB, CHI) to hit uncovered bins

Common Request Patterns¶

Pagination¶

All list tools support pagination:

{
  "page": 1,
  "page_size": 50,
  "sort_by": "created_at",
  "sort_order": "desc"
}

Response includes:

{
  "schema_version": "1.0.0",
  "page": 1,
  "page_size": 50,
  "total_items": 150,
  "total_pages": 3,
  "items": [...]
}

Filtering¶

Most tools support multiple filters (AND semantics):

{
  "status": "fail",
  "framework": "uvm",
  "name_contains": "axi"
}

Evidence Inclusion¶

Control evidence attachment:

{
  "include_evidence": true
}

Default: false (for performance)

Tool Selection Guide¶

"Why did this test fail?"¶

1. tests.list (find test by name/status)
2. failures.list (get failure events for test)
3. tests.topology (understand testbench structure)
4. assertions.failures (check assertion failures)

"What changed between runs?"¶

1. runs.diff (structured comparison)
2. coverage.summary (for both runs, if needed)

"Which tests cover this interface?"¶

1. tests.list (filter by name pattern)
2. tests.topology (check interface bindings)
3. coverage.summary (verify coverage)

"Show me top failures this week"¶

1. regressions.summary (time window + top signatures)
2. failures.list (detailed events for signature)

Error Handling¶

All tools return structured errors:

{
  "schema_version": "1.0.0",
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "page_size must be between 1 and 200",
    "details": {"field": "page_size", "value": "500"}
  }
}

Error codes:

NOT_FOUND - Resource doesn't exist
INVALID_ARGUMENT - Bad request parameters
PERMISSION_DENIED - Path sandboxing violation
INTERNAL - Server error
INDEX_NOT_READY - Index not built or stale
LIMIT_EXCEEDED - Response would exceed limits

"How do I close coverage?"¶

1. coverage.summary (identify low coverage runs)
2. coverage.gaps    (get prioritized gap list with recommendations)
3. coverage.advisor (get SV constraint code to hit specific uncovered bins)
4. runs.submit      (generate new run command to target gaps)

"Is my regression sign-off ready?"¶

1. regression.health (get 0–100 readiness score with breakdown)
2. coverage.trend    (check if coverage is trending upward)
3. runs.cross_sim    (verify no simulator divergence)

"Why are so many tests failing?"¶

1. tests.cluster     (group failures by root-cause signature)
2. failures.list     (drill into each cluster)
3. assertions.failures (check correlated assertion failures)

"Is my simulation still running?"¶

1. sim.status (check phase, percent_done, staleness)

"Replay a failing test with the same seed"¶

1. tests.list   (find the failing test ID)
2. tests.replay (get ready-to-paste replay command)