get-span-annotations
Retrieve span annotations, including metadata, scores, or labels, for specific span IDs. Use this tool to analyze and categorize spans in projects, with options to filter annotations and paginate results.
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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| excludeAnnotationNames | No | ||
| includeAnnotationNames | No | ||
| limit | No | ||
| projectName | Yes | ||
| spanIds | Yes |
Implementation Reference
- The asynchronous handler function that implements the core logic for the 'get-span-annotations' MCP tool. It builds query parameters based on input (projectName, spanIds, filters, pagination), calls the PhoenixClient's GET /span_annotations endpoint, and formats the response as MCP content with JSON stringified spans and cursor.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 for input validation of the 'get-span-annotations' tool parameters: required projectName and spanIds array, optional filters for annotation names, cursor, and limit.{ 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-200 (registration)MCP server registration of the 'get-span-annotations' tool using server.tool(), specifying the tool name, description constant, Zod input schema, and handler function within the initializeSpanTools export.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 ), }, ], }; } );
- Constant string providing the detailed description for the 'get-span-annotations' tool, used during registration.const GET_SPAN_ANNOTATIONS_DESCRIPTION = `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" }`;