product: maestro audience: test-developer, operator, ai-assistant authority: normative
MCP Tools — Statistics
Tools for querying yield, measurement capability, worst steps, and unit history.
Statistics are served from a pre-computed cache (written by StatisticsBackgroundService
in Orchestra) and fall back to live queries when the cache is stale or absent.
For a full conceptual guide including Cp/Cpk interpretation and example AI prompts,
see statistics.md.
All tool responses include a top-level station field containing the StationLabel
configured for this server instance.
See also:
tools-reference.mdfor the full tool index.
get_yield
Returns pass yield (%) for a test, optionally scoped to a step, station, and date range.
| Parameter | Type | Required | Description |
|---|---|---|---|
testName |
string | Yes | Name of the test definition |
stepName |
string | No | Step name — omit for test-level yield |
stationId |
string | No | Restrict to a single station |
from |
string | No | ISO 8601 start datetime (UTC), e.g. 2025-01-01T00:00:00Z |
to |
string | No | ISO 8601 end datetime (UTC) |
Returns: yield — testName, stepName, stationId, totalRuns, passCount, failCount, yieldPercent, from, to
Calls: GET /api/statistics/yield
list_measurement_names
Discovers valid measurement point names before querying statistics. Call this when you do
not know the exact measurementName required by get_measurement_statistics.
Results are deduplicated by name — each distinct name appears exactly once regardless of
how many times its limits have been changed. Each entry now includes pre-computed
sampleCount, cp, and cpk from the stat_cache, so you can identify poor-capability
measurements without making N follow-up calls.
To find all measurements below a Cpk threshold in one call, use
get_capability_summaryinstead.
| Parameter | Type | Required | Description |
|---|---|---|---|
search |
string | No | Case-insensitive substring filter, e.g. "VOUT" returns all VOUT_* names |
limit |
int | No | Maximum results to return (default 50, max 500) |
Returns: measurements — count, limit, search,
names[] (each has name, lowerLimit, upperLimit, units, definitionVersions,
sampleCount, cp, cpk)
Field notes:
| Field | Notes |
|---|---|
lowerLimit / upperLimit |
Indicative — taken from one definition version, not necessarily the most recent |
sampleCount |
From the stat_cache; null if no executions have completed yet |
cp / cpk |
From the stat_cache; null if no limits, σ = 0, or no samples yet |
definitionVersions |
> 1 means limits changed — see caveat below |
definitionVersions interpretation:
| Value | Meaning |
|---|---|
1 |
Specification limits have never changed — statistics are straightforward |
> 1 |
Limits were changed N−1 times. When you call get_measurement_statistics, always read the limitsNote field and present it to the user before any Cp/Cpk interpretation. The cp/cpk shown here are from the most-recently-computed cache entry and may not reflect pooled statistics. |
Calls: GET /api/statistics/measurement-names
get_capability_summary
Returns all measurement points whose Cpk is below a given threshold, sorted worst-first.
Served entirely from the pre-computed stat_cache — one call replaces N calls to
get_measurement_statistics when scanning a large population for poorly-performing
measurements.
| Parameter | Type | Required | Description |
|---|---|---|---|
maxCpk |
double | No | Return only measurements with Cpk strictly below this value (default 1.33) |
testName |
string | No | Restrict results to a single test definition |
stationId |
string | No | Restrict results to a single station |
limit |
int | No | Maximum results to return (default 50, max 200) |
Returns: summary — count, limit, maxCpk, testName, stationId,
items[] (each has measurementName, testName, stationId, sampleCount,
mean, stdDev, min, max, lowerLimit, upperLimit, units,
cp, cpk, definitionVersions, computedAt)
When multiple tests define the same measurement name, the item with the lowest Cpk across all tests is returned (one row per unique measurement name).
definitionVersions caveat: For measurements with definitionVersions > 1, the
cached statistics are per-definition rather than pooled across versions. Use
get_measurement_statistics for the definitive pooled Cp/Cpk in those cases.
Calls: GET /api/statistics/capability-summary
get_measurement_statistics
Returns descriptive statistics and process capability indices for a named numeric
measurement point. Use list_measurement_names first if you do not know the exact name.
Samples are pooled across all specification versions of the name so sampleCount always
reflects the full historical population — no silent truncation when limits change.
| Parameter | Type | Required | Description |
|---|---|---|---|
measurementName |
string | Yes | Exact measurement name from the test package |
testName |
string | No | Restrict sample set to one test |
stationId |
string | No | Restrict to a single station |
from |
string | No | ISO 8601 start datetime (UTC) |
to |
string | No | ISO 8601 end datetime (UTC) |
Returns: statistics — measurementName, testName, stationId, sampleCount,
mean, stdDev, min, max, lowerLimit, upperLimit, units,
cp, cpk, passCount, failCount, from, to,
definitionVersions, limitsNote
Critical fields — act on these before presenting results:
| Field | When to act |
|---|---|
definitionVersions |
If > 1, specification limits changed during the programme. Proceed to next row. |
limitsNote |
Non-null when definitionVersions > 1. Always show this text to the user before any Cp/Cpk interpretation. Do not omit it. |
lowerLimit / upperLimit |
Always from the most recently active specification. |
cp / cpk |
Computed against the most recently active limits. Null if limits undefined or σ = 0. |
Calls: GET /api/statistics/measurement
get_yield_trend
Returns yield bucketed over time for trend analysis.
| Parameter | Type | Required | Description |
|---|---|---|---|
testName |
string | Yes | Name of the test definition |
bucket |
string | No | "day" (default), "week", or "month" |
stationId |
string | No | Restrict to a single station |
from |
string | No | ISO 8601 start datetime (UTC) |
to |
string | No | ISO 8601 end datetime (UTC) |
Returns: trend — testName, stationId, bucket, points[]
Each point: bucketStart, bucketLabel, totalRuns, passCount, yieldPercent
Calls: GET /api/statistics/trend
get_worst_steps
Returns test steps ranked by pass rate ascending (worst-performing steps first). Useful for identifying systematic failure hotspots.
| Parameter | Type | Required | Description |
|---|---|---|---|
testName |
string | Yes | Name of the test definition |
stationId |
string | No | Restrict to a single station |
from |
string | No | ISO 8601 start datetime (UTC) |
to |
string | No | ISO 8601 end datetime (UTC) |
top |
int | No | Maximum steps to return (default 10, max 50) |
Returns: worstSteps[] — each has rank, stepName, testName, totalRuns, passCount, yieldPercent
Calls: GET /api/statistics/worst-steps
get_unit_history
Returns paginated test run history for a specific serial number, ordered newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
serialNumber |
string | Yes | Serial number of the unit under test |
page |
int | No | 1-based page number (default 1) |
pageSize |
int | No | Items per page (default 25, max 100) |
Returns: history — serialNumber, totalCount, page, pageSize,
items[] (each has executionId, testName, stationId, verdict, startTime, endTime, operatorId)
Calls: GET /api/statistics/unit-history
search_execution_logs
Runs a full-text search over indexed execution log chunks.
Logs are indexed by EmbeddingBackgroundService in Orchestra within 65 seconds of
execution completion.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | Yes | — | Plain-text search phrase. PostgreSQL tsquery operators &, \|, ! are supported. |
testExecutionId |
UUID | No | null | Restrict results to a single execution. |
stepName |
string | No | null | Restrict results to a specific step name. |
limit |
int | No | 20 | Results per page (1–100). |
page |
int | No | 1 | 1-based page number. |
Returns: results — query, testExecutionId, stepName, totalHits, page, pageSize,
hits[] (each: logEmbeddingId, testExecutionId, stepExecutionId, stepName, chunkIndex, textSnippet, embeddedAt, rank)
Calls: GET /api/statistics/logs
For a conceptual guide and example prompts see live-events.md.