---
title: "Rank a candidate tool against PiperMatch on a set of cases"
method: POST
path: "/v1/tools/probe"
tags: ["Tools"]
---

# Rank a candidate tool against PiperMatch on a set of cases

`POST /v1/tools/probe`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/tools/probe`
- Auth: HTTP bearer

Dev / CI fixture for retrieval-quality probes. Embeds the `candidate`
tool description against the live PiperMatch index and scores it on each
case in `cases` (or the legacy `queries` shorthand). Each case carries an
explicit `expect` — `"candidate"`, `{owner: "name"}`, or `"top_k"` (with
a sibling `top_k` integer). Aggregate `pass` is true when every case
passes its expectation by `min_margin`.

## Request body

- ToolProbeRequest
  - `candidate` ToolProbeCandidate, required
    - `name` string, required
    - `description` string, required
    - `when_to_use` string
  - `cases` ToolProbeCase[]: Probe cases. Mutually exclusive with `queries`.
    - `query` string, required
    - `expect` union: Expectation for this case. One of: * `"candidate"` — the candidate must rank #1. * `"top_k"` — the candidate must rank within `top_k` (sibling field). * `{ "owner": "<tool_name>" }` — the named tool must rank #1. Defaults to `"candidate"` when omitted.
      - 'candidate' | 'top_k'
      - object
        - `owner` string, required
    - `top_k` integer: Top-K bound when `expect: "top_k"`. Default 3.
  - `queries` string[]: Legacy shorthand — expands to `cases: [{query, expect: "candidate"}]`. Mutually exclusive with `cases`.
  - `min_margin` number: Minimum cosine margin a passing case must achieve over the runner-up. Default 0.03.

## Response `200`

Probe results (per-case + aggregate)

- ToolProbeResponse
  - `candidate` string, required
  - `cases_total` integer, required
  - `cases_passed` integer, required
  - `min_margin` number, required
  - `pass` boolean, required: True when every case passed its expectation by `min_margin`.
  - `results` ToolProbeCaseResult[], required
    - `query` string, required
    - `expect` union, required: Echoes the case's expectation in the same shape it was provided.
      - 'candidate' | 'top_k'
      - object
        - `owner` string, required
    - `pass` boolean, required
    - `candidate_score` number, required
    - `rank` integer, required
    - `margin_vs_runner_up` number, required
    - `top_entry` string, required
    - `top_score` number, required
    - `runner_up` string, required
    - `runner_up_score` number, required
    - `top_k` integer: Present when `expect: "top_k"`.
    - `note` string: Optional diagnostic note.

## Other responses

- `400`: Invalid request
- `500`: Probe execution failed
- `503`: ToolGate service or candidate embedding unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)