Skip to main content
Glama
avivsinai

langfuse-mcp

by avivsinai

list_scores_v2

Retrieve Langfuse scores with optional filters for name, trace, value, source, and timestamps to analyze LLM evaluation results.

Instructions

List scores via Scores API v3 with optional filters (GET /v2/scores where v3 is not served).

With operator ``=`` and a value, v3 defaults an omitted data_type to NUMERIC; pass BOOLEAN for boolean scores.
Strict ``>``/``<`` can return fewer than limit rows on a page after boundary rows are dropped; next_page shows whether more rows exist.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoOptional score name filter
pageNoPage number for pagination (starts at 1)
limitNoItems per page (max 100)
valueNoOptional numeric score value filter
sourceNoOptional score source filter
user_idNoOptional user ID filter (Scores API v3 has none: uses GET /v2/scores, which Langfuse Cloud removes on 2026-11-16)
operatorNoOptional comparison for value: =, >, >=, < or <= (default =)
queue_idNoOptional annotation queue ID
trace_idNoOptional trace ID
config_idNoOptional score config ID
data_typeNoOptional score data type
score_idsNoOptional comma-separated score IDs
session_idNoOptional session ID (not together with trace_id)
trace_tagsNoOptional comma-separated trace tags (Scores API v3 has none: uses GET /v2/scores, which Langfuse Cloud removes on 2026-11-16)
environmentNoOptional environment filter
to_timestampNoOptional ISO8601 timestamp upper bound
from_timestampNoOptional ISO8601 timestamp lower bound

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.12.1
    • changedInput schema / properties / operator / description
      Previous value: -"Optional operator filter"New value: +"Optional comparison for value: =, >, >=, < or <= (default =)"
    • changedInput schema / properties / session_id / description
      Previous value: -"Optional session ID"New value: +"Optional session ID (not together with trace_id)"
    • changedInput schema / properties / trace_tags / description
      Previous value: -"Optional comma-separated trace tags"New value: +"Optional comma-separated trace tags (Scores API v3 has none: uses GET /v2/scores, which Langfuse Cloud removes on 2026-11-16)"
    • changedInput schema / properties / user_id / description
      Previous value: -"Optional user ID filter"New value: +"Optional user ID filter (Scores API v3 has none: uses GET /v2/scores, which Langfuse Cloud removes on 2026-11-16)"
  2. Addedv0.9.0

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations provided, the description carries the behavioral burden. It discloses meaningful edge-case behavior: v3's default data_type of NUMERIC when using '=' with a value, the need to pass BOOLEAN explicitly, and the fact that strict '>'/'<' may drop boundary rows and return fewer pages, with next_page indicating more rows. This goes well beyond a bare action statement.

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

Conciseness5/5

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

Three dense sentences with no filler. The first sentence states purpose and endpoint, the second explains a key default behavior, and the third covers an important pagination edge case. Every sentence earns its place.

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

Completeness4/5

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

Given the tool's complexity (17 optional parameters, no required params, output schema present, no annotations), the description covers the most important non-obvious behaviors. It leaves structural details to the rich schema and output schema, which is appropriate, though it could have briefly noted the deprecation/removal context already present in the schema descriptions.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds extra semantic value by explaining the interaction between operator, value, and data_type defaults, plus the pagination caveat, which are not fully evident from the parameter descriptions alone.

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 a specific action ('List scores') and resource ('Scores API v3'), with the concrete endpoint and optional filters. It does not explicitly contrast with the sibling get_score_v2, though the plural form and endpoint imply a list operation, and the v2/v3 naming is slightly confusing.

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 implies usage: this is the tool for listing scores with optional filters, and it provides useful context about pagination and operator behavior. However, it does not explicitly state when to prefer this over get_score_v2 or any other sibling, nor does it give exclusions or prerequisites.

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