Skip to main content
Glama
Arize-ai

@arizeai/phoenix-mcp

Official
by Arize-ai

get-spans

Retrieve operation spans from a project with filters on time, trace, parent, name, kind, or status codes.

Instructions

Get spans from a project with filtering criteria.

Spans represent individual operations or units of work within a trace. They contain timing information, attributes, and context about the operation being performed.

Example usage: Get recent spans from project "my-project" Get spans in a time range from project "my-project"

Expected return: Object containing spans array and optional next cursor for pagination. Example: { "spans": [ { "id": "span123", "name": "http_request", "context": { "trace_id": "trace456", "span_id": "span123" }, "start_time": "2024-01-01T12:00:00Z", "end_time": "2024-01-01T12:00:01Z", "attributes": { "http.method": "GET", "http.url": "/api/users" } } ], "nextCursor": "cursor_for_pagination" }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
project_identifierNo
start_timeNo
end_timeNo
trace_idsNo
parent_idNo
namesNo
span_kindsNo
status_codesNo
cursorNo
limitNo
include_annotationsNo
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It includes an expected return format with an example, which adds transparency. However, it does not disclose behavioral traits such as potential side effects, authorization requirements, rate limits, or constraints on filtering. The example provides some context but not comprehensive behavioral depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long: it includes a conceptual explanation, example usage, and a full JSON example. The main action is front-loaded. However, some content (e.g., the full example object) could be considered excessive or redundant. It is adequate but not optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, no output schema, no annotations), the description should be highly complete. While it explains what spans are and shows a return example, it fails to detail the purpose of many filtering parameters or pagination (cursor, limit). It also lacks any mention of required parameters or default behaviors beyond limit. The description is incomplete for an agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 11 parameters with 0% description coverage (no parameter-level descriptions). The tool description mentions 'filtering criteria' and gives general examples but does not explain individual parameters like start_time, end_time, trace_ids, etc. This is insufficient compensation for the lack of schema descriptions, leaving much ambiguity for the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get spans from a project with filtering criteria') and explains what spans are. It includes example usage that reinforces the purpose. However, it does not explicitly distinguish itself from sibling tools like get-trace or list-traces, which reduces sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides example usage scenarios (recent spans, time range) that imply when to use the tool. However, it does not specify when not to use it or mention alternatives (e.g., get-trace for a single trace, list-traces for summary). The guidance is present but not explicit about exclusions or comparative context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Arize-ai/phoenix'

If you have feedback or need assistance with the MCP directory API, please join our Discord server