get-span-annotations
Retrieve metadata, scores, and labels for spans to analyze and categorize them in your project.
Instructions
Get span annotations for a list of span IDs.
Span annotations provide additional metadata, scores, or labels for spans. They can be created by humans, LLMs, or code and help in analyzing and categorizing spans.
Example usage: Get annotations for spans ["span1", "span2"] from project "my-project" Get quality score annotations for span "span1" from project "my-project"
Expected return: Object containing annotations array and optional next cursor for pagination. Example: { "annotations": [ { "id": "annotation123", "span_id": "span1", "name": "quality_score", "result": { "label": "good", "score": 0.95, "explanation": null }, "annotator_kind": "LLM", "metadata": { "model": "gpt-4" } } ], "nextCursor": "cursor_for_pagination" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectName | Yes | ||
| spanIds | Yes | ||
| includeAnnotationNames | No | ||
| excludeAnnotationNames | No | ||
| cursor | No | ||
| limit | No |
Implementation Reference
- Handler function that implements the get-span-annotations tool by querying the Phoenix API for span annotations based on project name, span IDs, filters, and pagination.
async ({ projectName, spanIds, includeAnnotationNames, excludeAnnotationNames, cursor, limit = 100, }) => { const params: NonNullable< Types["V1"]["operations"]["listSpanAnnotationsBySpanIds"]["parameters"]["query"] > = { span_ids: spanIds, limit, }; if (cursor) { params.cursor = cursor; } if (includeAnnotationNames) { params.include_annotation_names = includeAnnotationNames; } if (excludeAnnotationNames) { params.exclude_annotation_names = excludeAnnotationNames; } const response = await client.GET( "/v1/projects/{project_identifier}/span_annotations", { params: { path: { project_identifier: projectName, }, query: params, }, } ); return { content: [ { type: "text", text: JSON.stringify( { annotations: response.data?.data ?? [], nextCursor: response.data?.next_cursor ?? null, }, null, 2 ), }, ], }; } - Zod schema defining the input parameters for the get-span-annotations tool.
{ projectName: z.string(), spanIds: z.array(z.string()), includeAnnotationNames: z.array(z.string()).optional(), excludeAnnotationNames: z.array(z.string()).optional(), cursor: z.string().optional(), limit: z.number().min(1).max(1000).default(100).optional(), }, - js/packages/phoenix-mcp/src/spanTools.ts:134-202 (registration)Registration of the get-span-annotations tool with the MCP server inside initializeSpanTools function.
server.tool( "get-span-annotations", GET_SPAN_ANNOTATIONS_DESCRIPTION, { projectName: z.string(), spanIds: z.array(z.string()), includeAnnotationNames: z.array(z.string()).optional(), excludeAnnotationNames: z.array(z.string()).optional(), cursor: z.string().optional(), limit: z.number().min(1).max(1000).default(100).optional(), }, async ({ projectName, spanIds, includeAnnotationNames, excludeAnnotationNames, cursor, limit = 100, }) => { const params: NonNullable< Types["V1"]["operations"]["listSpanAnnotationsBySpanIds"]["parameters"]["query"] > = { span_ids: spanIds, limit, }; if (cursor) { params.cursor = cursor; } if (includeAnnotationNames) { params.include_annotation_names = includeAnnotationNames; } if (excludeAnnotationNames) { params.exclude_annotation_names = excludeAnnotationNames; } const response = await client.GET( "/v1/projects/{project_identifier}/span_annotations", { params: { path: { project_identifier: projectName, }, query: params, }, } ); return { content: [ { type: "text", text: JSON.stringify( { annotations: response.data?.data ?? [], nextCursor: response.data?.next_cursor ?? null, }, null, 2 ), }, ], }; } ); };