The earlier search tool returned a useful excerpt, but each learner still had to identify the report's conditions and numeric fields. Suppose a training team wants a single get_report_summary tool that returns the already prepared summary for one approved report ID. A narrow lookup is a better starting assignment than a general command runner: the desired behavior can be described completely, and a reviewer can compare the answer with the fixture by hand.
Target the same MCP 2025-11-25 teaching revision and local stdio setting. The proposed server advertises only tools, and tools/list exposes exactly get_report_summary. Its backing store contains the synthetic sta-01 and dv-02 entries described below. The fixed mapping is internal: a caller supplies an ID, never a path, URL, SQL expression, or shell command. This is an application design choice, not an isolation guarantee supplied by MCP.
DESIGN CONTRACT - not runnable server code
Tool: get_report_summary
Input object:
report_id: required string, enum ["sta-01", "dv-02"]
additional properties: rejected
Proposed structured output object:
synthetic: boolean, always true for this training fixture
snapshot: string, "training-r1"
report_id: string
kind: string
conditions: object containing string values
observations: array of {metric: string, value: number, unit: string}
source_lines: array of positive integers
limitations: array of strings
sta-01 fixture:
kind: "setup-summary"
conditions: {corner: "slow-demo", clock: "core_clk"}
observations: [{metric: "WNS", value: -0.08, unit: "ns"},
{metric: "violating_endpoints", value: 3, unit: "count"}]
source_lines: [12, 13, 14]
limitations: ["No detailed paths; no root-cause or signoff conclusion."]
dv-02 fixture:
kind: "failure-summary"
conditions: {test: "reset_release_demo", seed: "17", status: "FAIL"}
observations: [{metric: "reset_seen_expected", value: 1, unit: "boolean"},
{metric: "reset_seen_observed", value: 0, unit: "boolean"}]
source_lines: [21, 22]
limitations: ["One case only; cause and failure rate unknown."]Before implementing this design, a developer would turn both object contracts into actual JSON Schemas and validate requests and results. The 2025-11-25 tools specification describes inputSchema, optional outputSchema, structuredContent, and text content. For this proposal, advertise an output schema, return matching structured content, and include its serialized JSON in a text block for compatibility. The block above documents fields; it is not a complete tool declaration or a wire response.
An engineer asks for sta-01. After the same pinned initialization and inspection process taught earlier, the client proposes tools/call with name get_report_summary and arguments containing report_id equal to sta-01. The host checks its named-tool policy. The server checks the input contract, looks up the fixed fixture, and returns synthetic true, training-r1, the report ID, and the listed summary fields. The host validates the output and the skill checks whether the answer preserves conditions and limitations.
The expected user-facing result is the same bounded observation as before: negative WNS and three violating endpoints for the stated clock and corner. Structured fields reduce ambiguity about units and identity; they do not supply missing detailed paths. An RTL engineer still needs source context before editing logic, a DV engineer still needs sequence evidence before diagnosing reset, and a PD engineer still needs stage-specific reports before connecting timing to placement.
Paper review case | Expected behavior |
|---|---|
sta-01 with no extra fields | Return only the fixed STA summary, preserving numeric -0.08 and unit ns. |
dv-02 with no extra fields | Return the reset mismatch and FAIL condition, preserving seed as a string. |
report_id is ../private or a URL | Reject the input; never interpret it as a location or read anything. |
Valid report_id plus command field | Reject extra properties; do not ignore a requested command silently. |
Fixture unavailable | Return an explicit tool failure; do not fabricate a summary or claim zero violations. |
Returned observations omit units | Fail the proposed output checks and withhold an engineering conclusion. |
Write a review note for the extra command case and the unavailable fixture case. State which behavior belongs in the server and which belongs in the host. Finally, explain why adding a path argument would require a fresh review even if the tool retained its original name and read-only label.
The server rejects unexpected arguments and reports fixture failures truthfully; the host enforces the tool policy, validates results, and avoids unsupported conclusions. A path argument changes the data boundary and introduces filesystem interpretation, so the existing review no longer describes the interface. A familiar name or annotation does not preserve the old access guarantees.
This contract has not been implemented, connected, or tested. A real SDK starter should be written against the selected official SDK's current primary documentation, with protocol and package versions recorded separately; do not treat this design as copy-paste server code. The versioned transport specification also matters: for stdio, protocol output must stay separate from diagnostic logging. The reviewable deliverable here is a narrow contract, synthetic fixtures, and expected behavior, with no installation or execution required.