Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(mcp): Improve time filtering descriptions (#18930)

Ben Bachemacd0bcf66af7
diff --git a/web/src/__tests__/server/mcp-tools-read.servertest.ts b/web/src/__tests__/server/mcp-tools-read.servertest.ts
index b2028d9a97..321b1132e1 100644
--- a/web/src/__tests__/server/mcp-tools-read.servertest.ts
+++ b/web/src/__tests__/server/mcp-tools-read.servertest.ts
@@ -941,7 +941,7 @@ describe("MCP Read Tools", () => {
expect(result.fields.input.sensitive).toBe(true);
expect(result.fields.input.requiresScope).toBe(true);
expect(result.fields.input.scopeRequirement).toMatch(
- /requires both fromStartTime and toStartTime.*maximum range of 14 days.*even when scoped by traceId or observation id/i,
+ /requires both fromStartTime.*toStartTime.*even when scoped by traceId or observation id.*listObservations.*14 days \(336 elapsed hours\).*getObservation.*90 days \(2160 elapsed hours\)/i,
);
expect(result.fields.output.requiresScope).toBe(true);
expect(result.fields.metadata.expensive).toBe(true);
@@ -1140,19 +1140,22 @@ describe("MCP Read Tools", () => {
},
);
- it("should reject list periods longer than 14 days without payload fields", async () => {
- await expect(
- handleListObservations(
- {
- fromStartTime: "2026-01-01T00:00:00.000Z",
- toStartTime: "2026-01-15T00:00:00.001Z",
- fields: ["id"],
- limit: 1,
- },
- mockServerContext(),
- ),
- ).rejects.toThrow(/maximum range of 14 days/i);
- });
+ it.each(["2026-01-15T00:00:00.001Z", "2026-01-15T23:59:59.000Z"])(
+ "should reject list periods exceeding 336 hours: %s",
+ async (toStartTime) => {
+ await expect(
+ handleListObservations(
+ {
+ fromStartTime: "2026-01-01T00:00:00.000Z",
+ toStartTime,
+ fields: ["id"],
+ limit: 1,
+ },
+ mockServerContext(),
+ ),
+ ).rejects.toThrow(/maximum range of 14 days \(336 elapsed hours\)/i);
+ },
+ );
it("should advertise required bounds for both tools", () => {
for (const tool of [getObservationTool, listObservationsTool]) {
diff --git a/web/src/features/mcp/server/experiments/schema.ts b/web/src/features/mcp/server/experiments/schema.ts
index 274a5aacc6..53fe513b4c 100644
--- a/web/src/features/mcp/server/experiments/schema.ts
+++ b/web/src/features/mcp/server/experiments/schema.ts
@@ -10,6 +10,12 @@ import { z } from "zod";
import { McpAdvancedFilterBaseSchema } from "../../core/filter-schema";
export const ListExperimentsBaseSchema = GetExperimentsV1ParsedQuery.extend({
+ fromStartTime: GetExperimentsV1ParsedQuery.shape.fromStartTime.describe(
+ "Required lower time bound for the events scanned before grouping experiments, as an ISO 8601 timestamp with timezone (Z or an explicit offset). This does not filter directly on the returned experiment startTime; aggregates may be partial.",
+ ),
+ toStartTime: GetExperimentsV1ParsedQuery.shape.toStartTime.describe(
+ "Optional upper time bound for the events scanned before grouping experiments, as an ISO 8601 timestamp with timezone. Omit to leave the upper bound open. Aggregates only include events within the requested time window.",
+ ),
// MCP callers pass the encoded cursor string; runtime validation decodes it.
cursor: EncodedExperimentsCursorString.optional(),
// MCP JSON Schema generation cannot represent the public filter union/intersection.
@@ -25,6 +31,13 @@ export const ListExperimentsInputSchema = GetExperimentsV1ParsedQuery;
export const ListExperimentItemsBaseSchema =
GetExperimentItemsV1ParsedQueryBase.extend({
+ fromStartTime:
+ GetExperimentItemsV1ParsedQueryBase.shape.fromStartTime.describe(
+ "Required lower bound on experiment item startTime, as an ISO 8601 timestamp with timezone (Z or an explicit offset).",
+ ),
+ toStartTime: GetExperimentItemsV1ParsedQueryBase.shape.toStartTime.describe(
+ "Optional upper bound on experiment item startTime, as an ISO 8601 timestamp with timezone. Omit to leave the upper bound open.",
+ ),
// MCP callers pass the encoded cursor string; runtime validation decodes it.
cursor: EncodedExperimentsCursorString.optional(),
// MCP JSON Schema generation cannot represent the public filter union/intersection.
diff --git a/web/src/features/mcp/server/metrics/tools/queryMetrics.ts b/web/src/features/mcp/server/metrics/tools/queryMetrics.ts
index 175d102973..1d3a3f117d 100644
--- a/web/src/features/mcp/server/metrics/tools/queryMetrics.ts
+++ b/web/src/features/mcp/server/metrics/tools/queryMetrics.ts
@@ -123,8 +123,16 @@ const MetricsQueryObjectV2BaseSchema = z.object({
granularity: publicGranularities,
})
.optional(),
- fromTimestamp: z.iso.datetime({ offset: true }),
- toTimestamp: z.iso.datetime({ offset: true }),
+ fromTimestamp: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required start of the analytics time range, as an ISO 8601 timestamp with timezone (Z or an explicit offset). Must be before toTimestamp.",
+ ),
+ toTimestamp: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required end of the analytics time range, as an ISO 8601 timestamp with timezone. Must be after fromTimestamp. timeDimension.granularity controls aggregation buckets; it does not replace these explicit time bounds.",
+ ),
orderBy: z
.array(
z.object({
diff --git a/web/src/features/mcp/server/observations/schema.ts b/web/src/features/mcp/server/observations/schema.ts
index 87d5d0b674..3efde8db9f 100644
--- a/web/src/features/mcp/server/observations/schema.ts
+++ b/web/src/features/mcp/server/observations/schema.ts
@@ -36,7 +36,7 @@ type ObservationMcpFieldType =
| "unknown";
const EXPENSIVE_FIELD_SCOPE_REQUIREMENT =
- "Requires both fromStartTime and toStartTime with a maximum range of 14 days, even when scoped by traceId or observation id.";
+ "Requires both fromStartTime (inclusive) and toStartTime (exclusive), even when scoped by traceId or observation id. listObservations allows a maximum range of 14 days (336 elapsed hours); getObservation allows 90 days (2160 elapsed hours). Limits measure elapsed time, not calendar dates.";
const OBSERVATION_MCP_FIELDS = OBSERVATION_FIELD_GROUPS_PUBLIC_API.flatMap(
(group) => OBSERVATION_FIELD_GROUP_FIELD_NAMES[group],
diff --git a/web/src/features/mcp/server/observations/tools/getObservation.ts b/web/src/features/mcp/server/observations/tools/getObservation.ts
index c37efeb92d..cae34b88d0 100644
--- a/web/src/features/mcp/server/observations/tools/getObservation.ts
+++ b/web/src/features/mcp/server/observations/tools/getObservation.ts
@@ -22,8 +22,16 @@ const MCP_OBSERVATIONS_MAX_EXECUTION_TIME_SECONDS = 25;
const GetObservationBaseSchema = z.object({
observationId: z.string().min(1),
traceId: z.string().min(1).optional(),
- fromStartTime: z.iso.datetime({ offset: true }),
- toStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required inclusive lower bound on observation startTime, as an ISO 8601 timestamp with timezone (Z or an explicit offset). Must be before toStartTime; the elapsed duration must not exceed 90 days (2160 hours).",
+ ),
+ toStartTime: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required exclusive upper bound on observation startTime, as an ISO 8601 timestamp with timezone. Must be after fromStartTime and at most 2160 hours later. The observation's startTime must be strictly before this bound.",
+ ),
fields: ObservationFieldsSchema,
expandMetadataKeys: ExpandMetadataKeysSchema,
});
@@ -33,7 +41,7 @@ export const [getObservationTool, handleGetObservation] = defineTool({
description: [
"Get the details for a single observation in the current Langfuse project by observation ID.",
"Use this when you already know the observation ID and want to inspect its timing, model, status, payload, metadata, usage, cost, or prompt fields.",
- "Requires explicit fromStartTime and toStartTime with a positive range of at most 90 days. Reuse the observation startTime and traceId from earlier results to narrow the lookup; traceId does not replace time bounds.",
+ "Requires explicit fromStartTime (inclusive) and toStartTime (exclusive) with 0 < toStartTime - fromStartTime <= 2160 hours (90 days). The limit measures elapsed time, not calendar dates; do not extend the upper bound to the end of the 90th day. Reuse the observation startTime and traceId from earlier results to narrow the lookup; traceId does not replace time bounds. When using the observation startTime as fromStartTime, choose a later toStartTime.",
"",
'By default this returns compact summary fields. Use fields: ["*"] for the full observation, or pass specific field names to limit the response size.',
'Important: if you request metadata explicitly, for example fields: ["id", "metadata"], metadata values are truncated to 200 UTF-8 characters per key unless you also pass expandMetadataKeys with the keys that may need full values.',
@@ -49,7 +57,7 @@ export const [getObservationTool, handleGetObservation] = defineTool({
},
{
message:
- "getObservation requires fromStartTime before toStartTime with a maximum range of 90 days.",
+ "getObservation requires fromStartTime before toStartTime with a maximum range of 90 days (2160 elapsed hours). Use a narrower window containing the observation startTime; toStartTime is exclusive.",
path: ["toStartTime"],
},
),
diff --git a/web/src/features/mcp/server/observations/tools/getObservationFilterValues.ts b/web/src/features/mcp/server/observations/tools/getObservationFilterValues.ts
index 4d57664bf0..a6eb261b40 100644
--- a/web/src/features/mcp/server/observations/tools/getObservationFilterValues.ts
+++ b/web/src/features/mcp/server/observations/tools/getObservationFilterValues.ts
@@ -45,8 +45,18 @@ type FilterValueColumn = z.infer<typeof FilterValueColumnSchema>;
const GetObservationFilterValuesBaseSchema = z.object({
column: FilterValueColumnSchema,
- fromStartTime: z.iso.datetime({ offset: true }).optional(),
- toStartTime: z.iso.datetime({ offset: true }).optional(),
+ fromStartTime: z.iso
+ .datetime({ offset: true })
+ .optional()
+ .describe(
+ "Optional inclusive lower bound on observation startTime, as an ISO 8601 timestamp with timezone (Z or an explicit offset). Use the same time window as the observations you intend to search.",
+ ),
+ toStartTime: z.iso
+ .datetime({ offset: true })
+ .optional()
+ .describe(
+ "Optional exclusive upper bound on observation startTime, as an ISO 8601 timestamp with timezone. For a full calendar day, use midnight at the start of the next day, not 23:59:59.",
+ ),
observationType: ObservationTypeDomain.optional(),
isRootObservation: z.boolean().optional(),
hasParentObservation: z.boolean().optional(),
diff --git a/web/src/features/mcp/server/observations/tools/listObservations.ts b/web/src/features/mcp/server/observations/tools/listObservations.ts
index 6342ab9dbb..34958b774c 100644
--- a/web/src/features/mcp/server/observations/tools/listObservations.ts
+++ b/web/src/features/mcp/server/observations/tools/listObservations.ts
@@ -287,8 +287,16 @@ const ListObservationsBaseSchema = z.object({
.describe(
"Environment to filter by. Multiple environments are temporarily unsupported until the public observations API applies allow-multiple environment filters correctly.",
),
- fromStartTime: z.iso.datetime({ offset: true }),
- toStartTime: z.iso.datetime({ offset: true }),
+ fromStartTime: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required inclusive lower bound on observation startTime, as an ISO 8601 timestamp with timezone (Z or an explicit offset). Must be before toStartTime; the elapsed duration must not exceed 14 days (336 hours).",
+ ),
+ toStartTime: z.iso
+ .datetime({ offset: true })
+ .describe(
+ "Required exclusive upper bound on observation startTime, as an ISO 8601 timestamp with timezone. Must be after fromStartTime and at most 336 hours later. For 14 full UTC calendar days starting 2026-10-01T00:00:00Z, use 2026-10-15T00:00:00Z, not 2026-10-15T23:59:59Z. Split longer ranges into adjacent requests of at most 336 hours each.",
+ ),
filter: z
.array(ObservationMcpFilterBaseSchema)
.optional()
@@ -317,7 +325,7 @@ const assertAllowedObservationAccess = (
new Date(input.fromStartTime).getTime();
if (rangeMs <= 0 || rangeMs > OBSERVATION_MAX_RANGE_MS) {
throw new InvalidRequestError(
- "listObservations requires fromStartTime before toStartTime with a maximum range of 14 days.",
+ "listObservations requires fromStartTime before toStartTime with a maximum range of 14 days (336 elapsed hours). For example, 2026-10-01T00:00:00Z to 2026-10-15T00:00:00Z is valid; 2026-10-15T23:59:59Z exceeds the limit. Split longer ranges into adjacent requests of at most 336 hours each.",
);
}
@@ -337,11 +345,11 @@ export const [listObservationsTool, handleListObservations] = defineTool({
"Find and review observations in the current Langfuse project, such as generations, spans, events, agent steps, and tool calls.",
"Traces consist of observations. Use this tool when the user asks to inspect traces: pass traceId to page through the observations for a specific trace; those observation records are the trace data returned by the API.",
"Use filters to narrow results by trace, name, type, level, environment, time range, or advanced filter conditions. Results are paginated with an opaque cursor.",
- 'For metadata filters, first inspect metadata by passing both fromStartTime and toStartTime with a maximum range of 14 days and fields: ["id", "metadata"]. Then use a discovered key in a stringObject filter.',
+ 'For metadata filters, first inspect metadata by passing both fromStartTime and toStartTime with a maximum range of 14 days (336 elapsed hours) and fields: ["id", "metadata"]. Then use a discovered key in a stringObject filter.',
"",
'By default this returns compact summary fields. Use fields: ["*"] for the full observation, or pass specific field names to limit the response size.',
'Important: if you request metadata explicitly, for example fields: ["id", "metadata"], metadata values are truncated to 200 UTF-8 characters per key unless you also pass expandMetadataKeys with the keys that may need full values.',
- "All requests must include explicit fromStartTime and toStartTime with a positive date range of at most 14 days, even when scoped by traceId or observation id. Reuse timestamps from earlier results to narrow the search. Input/output projections support a maximum limit of 50.",
+ "All requests must include explicit fromStartTime (inclusive) and toStartTime (exclusive) with 0 < toStartTime - fromStartTime <= 336 hours (14 days), even when scoped by traceId or observation id. This is elapsed time, not a count of calendar dates. For example, 2026-10-01T00:00:00Z to 2026-10-15T00:00:00Z is valid; ending at 2026-10-15T23:59:59Z exceeds the limit. Split longer ranges into adjacent windows, using each window's toStartTime as the next window's fromStartTime. Reuse timestamps from earlier results to narrow the search. Input/output projections support a maximum limit of 50.",
].join("\n"),
action: "traces:read",
baseSchema: ListObservationsBaseSchema,
diff --git a/web/src/features/mcp/server/scores/tools/listScores.ts b/web/src/features/mcp/server/scores/tools/listScores.ts
index ba3e7e1c1f..393aed8109 100644
--- a/web/src/features/mcp/server/scores/tools/listScores.ts
+++ b/web/src/features/mcp/server/scores/tools/listScores.ts
@@ -47,8 +47,18 @@ const ListScoresBaseSchema = z
.array(z.string())
.optional()
.describe("same ID as datasetRunId in createScore"),
- fromTimestamp: z.iso.datetime({ offset: true }).optional(),
- toTimestamp: z.iso.datetime({ offset: true }).optional(),
+ fromTimestamp: z.iso
+ .datetime({ offset: true })
+ .optional()
+ .describe(
+ "Optional inclusive lower bound on the score timestamp, as an ISO 8601 timestamp with timezone (Z or an explicit offset). Filters scores by their own timestamp, not the associated observation's startTime.",
+ ),
+ toTimestamp: z.iso
+ .datetime({ offset: true })
+ .optional()
+ .describe(
+ "Optional exclusive upper bound on the score timestamp, as an ISO 8601 timestamp with timezone. For a full calendar day, use midnight at the start of the next day, not 23:59:59.",
+ ),
})
.strict();