get-experiment-by-id
Retrieve experiment metadata and results by ID, including outputs, annotations, and evaluator scores for analysis.
Instructions
Get an experiment by its ID.
The tool returns experiment metadata in the first content block and a JSON object with the experiment data in the second. The experiment data contains both the results of each experiment run and the annotations made by an evaluator to score or label the results, for example, comparing the output of an experiment run to the expected output from the dataset example.
Example usage: Show me the experiment results for experiment RXhwZXJpbWVudDo4
Expected return: Object containing experiment metadata and results. Example: { "metadata": { "id": "experimentid1234", "dataset_id": "datasetid1234", "dataset_version_id": "datasetversionid1234", "repetitions": 1, "metadata": {}, "project_name": "Experiment-abc123", "created_at": "YYYY-MM-DDTHH:mm:ssZ", "updated_at": "YYYY-MM-DDTHH:mm:ssZ" }, "experimentResult": [ { "example_id": "exampleid1234", "repetition_number": 0, "input": "Sample input text", "reference_output": "Expected output text", "output": "Actual output text", "error": null, "latency_ms": 1000, "start_time": "2025-03-20T12:00:00Z", "end_time": "2025-03-20T12:00:01Z", "trace_id": "trace-123", "prompt_token_count": 10, "completion_token_count": 20, "annotations": [ { "name": "quality", "annotator_kind": "HUMAN", "label": "good", "score": 0.9, "explanation": "Output matches expected format", "trace_id": "trace-456", "error": null, "metadata": {}, "start_time": "YYYY-MM-DDTHH:mm:ssZ", "end_time": "YYYY-MM-DDTHH:mm:ssZ" } ] } ] }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| experiment_id | Yes |
Implementation Reference
- Handler function that fetches experiment metadata and results data using parallel API calls to PhoenixClient and returns formatted JSON content.async ({ experiment_id }) => { const [experimentMetadataResponse, experimentDataResponse] = await Promise.all([ client.GET("/v1/experiments/{experiment_id}", { params: { path: { experiment_id, }, }, }), client.GET("/v1/experiments/{experiment_id}/json", { params: { path: { experiment_id, }, }, }), ]); const text = JSON.stringify({ metadata: experimentMetadataResponse.data?.data, experimentResult: experimentDataResponse.data, }); return { content: [{ type: "text", text }], }; }
- Input schema validation using Zod: requires a string 'experiment_id' parameter.{ experiment_id: z.string(), },
- js/packages/phoenix-mcp/src/experimentTools.ts:118-150 (registration)Direct registration of the 'get-experiment-by-id' tool with the MCP server, including name, description reference, input schema, and handler function.server.tool( "get-experiment-by-id", GET_EXPERIMENT_DESCRIPTION, { experiment_id: z.string(), }, async ({ experiment_id }) => { const [experimentMetadataResponse, experimentDataResponse] = await Promise.all([ client.GET("/v1/experiments/{experiment_id}", { params: { path: { experiment_id, }, }, }), client.GET("/v1/experiments/{experiment_id}/json", { params: { path: { experiment_id, }, }, }), ]); const text = JSON.stringify({ metadata: experimentMetadataResponse.data?.data, experimentResult: experimentDataResponse.data, }); return { content: [{ type: "text", text }], }; } );
- js/packages/phoenix-mcp/src/index.ts:41-41 (registration)High-level initialization call that registers all experiment tools, including 'get-experiment-by-id', by invoking initializeExperimentTools.initializeExperimentTools({ client, server });