Skip to content

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

fix(mcp): Limit observations tools for better performance (#18734)

Ben Bachem78e369340204
diff --git a/packages/shared/src/eventsTable.ts b/packages/shared/src/eventsTable.ts
index 931fefd8a7..f831708f7e 100644
--- a/packages/shared/src/eventsTable.ts
+++ b/packages/shared/src/eventsTable.ts
@@ -550,10 +550,11 @@ export const isNumericEventsTableColumnId = (
);
// Subset of columns that are allowed to be used as filters in the MCP observations API
+// listObservations has explicit fromStartTime and toStartTime arguments to bound database scans.
+// A startTime condition in its filter array would replace both bounds, bypassing the 14-day limit.
const OBSERVATION_MCP_ALLOWED_EVENTS_TABLE_FILTER_COLUMN_IDS = [
"id",
"traceId",
- "startTime",
"endTime",
"name",
"type",
diff --git a/web/src/__tests__/server/mcp-tools-read.servertest.ts b/web/src/__tests__/server/mcp-tools-read.servertest.ts
index e97b0a4f51..b2028d9a97 100644
--- a/web/src/__tests__/server/mcp-tools-read.servertest.ts
+++ b/web/src/__tests__/server/mcp-tools-read.servertest.ts
@@ -198,6 +198,11 @@ import {
GetDatasetsMcpInput,
} from "@/src/features/mcp/server/datasets/schema";
+const observationWindow = {
+ fromStartTime: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+ toStartTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+};
+
const maybeEventsTable =
env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN === "true"
? describe
@@ -991,6 +996,7 @@ describe("MCP Read Tools", () => {
expect(result.columns.output.operators).toEqual(["=", "matches"]);
expect(result.columns.version.operators).not.toContain("matches");
expect(result.columns.traceTags).toBeUndefined();
+ expect(result.columns.startTime).toBeUndefined();
expect(result.columns.comments).toBeUndefined();
expect(result.columns.scores).toBeUndefined();
expect(result.columns.name.operators).toContain("any of");
@@ -1046,6 +1052,7 @@ describe("MCP Read Tools", () => {
handleListObservations(
{
traceId: randomUUID(),
+ ...observationWindow,
filter: [
{
type: "string",
@@ -1061,6 +1068,101 @@ describe("MCP Read Tools", () => {
),
).rejects.toThrow();
});
+ describe("observation time bounds", () => {
+ it.each([true, false])(
+ "should reject startTime filters with explicit type: %s",
+ async (includeType) => {
+ await expect(
+ handleListObservations(
+ {
+ ...observationWindow,
+ fields: ["id"],
+ limit: 1,
+ filter: [
+ {
+ column: "startTime",
+ operator: ">=",
+ value: "2020-01-01T00:00:00Z",
+ ...(includeType ? { type: "datetime" } : {}),
+ },
+ ],
+ } as unknown as Parameters<typeof handleListObservations>[0],
+ mockServerContext(),
+ ),
+ ).rejects.toThrow('Invalid observation filter column "startTime"');
+ },
+ );
+
+ it.each(["fromStartTime", "toStartTime"] as const)(
+ "should require %s for both tools even with compact fields",
+ async (missingBound) => {
+ const input = { ...observationWindow, [missingBound]: undefined };
+ await expect(
+ handleListObservations(
+ { ...input, fields: ["id"], limit: 1 } as unknown as Parameters<
+ typeof handleListObservations
+ >[0],
+ mockServerContext(),
+ ),
+ ).rejects.toThrow(missingBound);
+ await expect(
+ handleGetObservation(
+ {
+ ...input,
+ observationId: randomUUID(),
+ fields: ["id"],
+ } as unknown as Parameters<typeof handleGetObservation>[0],
+ mockServerContext(),
+ ),
+ ).rejects.toThrow(missingBound);
+ },
+ );
+
+ it.each([
+ ["2026-01-01T00:00:00.000Z", "2026-01-01T00:00:00.000Z"],
+ ["2026-01-02T00:00:00.000Z", "2026-01-01T00:00:00.000Z"],
+ ["2026-01-01T00:00:00.000Z", "2026-04-01T00:00:00.001Z"],
+ ])(
+ "should reject invalid periods %s to %s",
+ async (fromStartTime, toStartTime) => {
+ await expect(
+ handleListObservations(
+ { fromStartTime, toStartTime, fields: ["id"], limit: 1 },
+ mockServerContext(),
+ ),
+ ).rejects.toThrow(/maximum range of 14 days/i);
+ await expect(
+ handleGetObservation(
+ { fromStartTime, toStartTime, observationId: randomUUID() },
+ mockServerContext(),
+ ),
+ ).rejects.toThrow(/maximum range of 90 days/i);
+ },
+ );
+
+ 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("should advertise required bounds for both tools", () => {
+ for (const tool of [getObservationTool, listObservationsTool]) {
+ expect(tool.inputSchema.required).toEqual(
+ expect.arrayContaining(["fromStartTime", "toStartTime"]),
+ );
+ }
+ });
+ });
+
maybeEventsTable("listObservations tool", () => {
it("should have readOnlyHint annotation", () => {
verifyToolAnnotations(listObservationsTool, { readOnlyHint: true });
@@ -1218,7 +1320,7 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleListObservations(
- { traceId, limit: 100 },
+ { ...observationWindow, traceId, limit: 100 },
context,
)) as {
data: Array<Record<string, unknown>>;
@@ -1262,7 +1364,7 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleListObservations(
- { traceId, fields: ["id"], limit: 100 },
+ { ...observationWindow, traceId, fields: ["id"], limit: 100 },
{ ...context, inAppAgent: { permissions: "read" } },
)) as { data: Array<{ id: string; url: string }> };
@@ -1288,7 +1390,12 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleListObservations(
- { traceId, fields: ["id", "name", "type"], limit: 100 },
+ {
+ ...observationWindow,
+ traceId,
+ fields: ["id", "name", "type"],
+ limit: 100,
+ },
context,
)) as { data: Array<Record<string, unknown>> };
@@ -1375,6 +1482,7 @@ describe("MCP Read Tools", () => {
},
],
fields: ["id", "userId"],
+ ...observationWindow,
limit: 100,
},
context,
@@ -1414,6 +1522,7 @@ describe("MCP Read Tools", () => {
{
traceId,
isRootObservation: true,
+ ...observationWindow,
fields: ["id", "parentObservationId", "isRootObservation"],
limit: 100,
},
@@ -1510,8 +1619,13 @@ describe("MCP Read Tools", () => {
const { context } = await createMcpTestSetup();
await expect(
- handleListObservations({ fields: ["input"], limit: 100 }, context),
- ).rejects.toThrow(/requires both fromStartTime and toStartTime/i);
+ handleListObservations(
+ { fields: ["input"], limit: 100 } as unknown as Parameters<
+ typeof handleListObservations
+ >[0],
+ context,
+ ),
+ ).rejects.toThrow(/fromStartTime.*toStartTime/i);
await expect(
handleListObservations(
@@ -1526,10 +1640,10 @@ describe("MCP Read Tools", () => {
},
],
limit: 100,
- },
+ } as unknown as Parameters<typeof handleListObservations>[0],
context,
),
- ).rejects.toThrow(/requires both fromStartTime and toStartTime/i);
+ ).rejects.toThrow(/fromStartTime.*toStartTime/i);
await expect(
handleListObservations(
@@ -1544,17 +1658,21 @@ describe("MCP Read Tools", () => {
},
],
limit: 100,
- },
+ } as unknown as Parameters<typeof handleListObservations>[0],
context,
),
- ).rejects.toThrow(/requires both fromStartTime and toStartTime/i);
+ ).rejects.toThrow(/fromStartTime.*toStartTime/i);
await expect(
handleListObservations(
- { traceId: randomUUID(), fields: ["metadata"], limit: 50 },
+ {
+ traceId: randomUUID(),
+ fields: ["metadata"],
+ limit: 50,
+ } as unknown as Parameters<typeof handleListObservations>[0],
context,
),
- ).rejects.toThrow(/requires both fromStartTime and toStartTime/i);
+ ).rejects.toThrow(/fromStartTime.*toStartTime/i);
await expect(
handleListObservations(
@@ -1646,10 +1764,12 @@ describe("MCP Read Tools", () => {
await expect(
handleListObservations(
- { ...scope, fields: ["input"], limit: 50 },
+ { ...scope, fields: ["input"], limit: 50 } as unknown as Parameters<
+ typeof handleListObservations
+ >[0],
context,
),
- ).rejects.toThrow(/requires both fromStartTime and toStartTime/i);
+ ).rejects.toThrow(/fromStartTime.*toStartTime/i);
await expect(
handleListObservations(
@@ -1734,6 +1854,7 @@ describe("MCP Read Tools", () => {
{ column: "totalCost", operator: ">", value: 0.0029 } as any,
],
fields: ["id", "name"],
+ ...observationWindow,
limit: 100,
},
context,
@@ -1767,6 +1888,7 @@ describe("MCP Read Tools", () => {
},
],
limit: 100,
+ ...observationWindow,
},
context,
),
@@ -1788,6 +1910,7 @@ describe("MCP Read Tools", () => {
},
],
limit: 100,
+ ...observationWindow,
},
context,
),
@@ -1805,6 +1928,7 @@ describe("MCP Read Tools", () => {
},
],
limit: 100,
+ ...observationWindow,
},
context,
),
@@ -1844,6 +1968,7 @@ describe("MCP Read Tools", () => {
},
],
fields: ["id"],
+ ...observationWindow,
limit: 100,
},
context,
@@ -1881,7 +2006,13 @@ describe("MCP Read Tools", () => {
]);
const result = (await handleListObservations(
- { traceId, fields: ["id"], limit: 1 },
+ {
+ traceId,
+ fields: ["id"],
+ limit: 1,
+ fromStartTime: "2026-01-01T00:00:00.000Z",
+ toStartTime: "2026-01-03T00:00:00.000Z",
+ },
context,
)) as { data: Array<{ id: string }>; meta: { cursor?: string } };
@@ -1893,12 +2024,15 @@ describe("MCP Read Tools", () => {
const { context } = await createMcpTestSetup();
await expect(
- handleListObservations({ fields: ["*", "id"], limit: 50 }, context),
+ handleListObservations(
+ { ...observationWindow, fields: ["*", "id"], limit: 50 },
+ context,
+ ),
).rejects.toThrow(/mixed wildcard projection/i);
await expect(
handleListObservations(
- { fields: ["unknownField"], limit: 50 },
+ { ...observationWindow, fields: ["unknownField"], limit: 50 },
context,
),
).rejects.toThrow(/getObservationFieldSchema/i);
@@ -1908,7 +2042,7 @@ describe("MCP Read Tools", () => {
const { context } = await createMcpTestSetup();
await expect(
- handleListObservations({ limit: 101 }, context),
+ handleListObservations({ ...observationWindow, limit: 101 }, context),
).rejects.toThrow(/<=100/i);
});
@@ -1926,11 +2060,11 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result1 = (await handleListObservations(
- { traceId, fields: ["id"], limit: 100 },
+ { ...observationWindow, traceId, fields: ["id"], limit: 100 },
context1,
)) as { data: Array<{ id: string }> };
const result2 = (await handleListObservations(
- { traceId, fields: ["id"], limit: 100 },
+ { ...observationWindow, traceId, fields: ["id"], limit: 100 },
context2,
)) as { data: Array<{ id: string }> };
@@ -2518,7 +2652,14 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleGetObservation(
- { observationId: observation.id },
+ {
+ observationId: observation.id,
+ traceId: observation.trace_id,
+ fromStartTime: new Date(
+ Date.now() - 89 * 24 * 60 * 60 * 1000,
+ ).toISOString(),
+ toStartTime: new Date(Date.now() + 1000).toISOString(),
+ },
context,
)) as Record<string, unknown>;
@@ -2539,6 +2680,77 @@ describe("MCP Read Tools", () => {
expect(result.metadata).toBeUndefined();
});
+ it("should not fetch an observation outside the period or with a different traceId", async () => {
+ const { context, projectId } = await createMcpTestSetup();
+ const observation = createObservationEvent({ projectId });
+ await createEventsCh([observation]);
+
+ for (const scope of [
+ { ...observationWindow, traceId: randomUUID() },
+ {
+ fromStartTime: "2026-01-01T00:00:00.000Z",
+ toStartTime: "2026-01-02T00:00:00.000Z",
+ },
+ ]) {
+ await expect(
+ handleGetObservation(
+ { observationId: observation.id, ...scope },
+ context,
+ ),
+ ).rejects.toThrow(/not found within the supplied period/i);
+ }
+ });
+
+ it("should enforce the plan data-access window for single observations", async () => {
+ const { context, projectId } = await createMcpTestSetup();
+ const now = Date.now();
+ const oldObservation = createObservationEvent({
+ projectId,
+ startTime: new Date(now - 40 * 24 * 60 * 60 * 1000),
+ });
+ const recentObservation = createObservationEvent({ projectId });
+ await createEventsCh([oldObservation, recentObservation]);
+
+ const period = {
+ fromStartTime: new Date(now - 60 * 24 * 60 * 60 * 1000).toISOString(),
+ toStartTime: new Date(now + 24 * 60 * 60 * 1000).toISOString(),
+ fields: ["id"],
+ };
+ const limitedContext = { ...context, plan: "cloud:hobby" as const };
+
+ await expect(
+ handleGetObservation(
+ { ...period, observationId: oldObservation.id },
+ limitedContext,
+ ),
+ ).rejects.toThrow(/not found within the supplied period/i);
+
+ await expect(
+ handleGetObservation(
+ { ...period, observationId: recentObservation.id },
+ limitedContext,
+ ),
+ ).resolves.toMatchObject({ id: recentObservation.id });
+
+ await expect(
+ handleGetObservation(
+ { ...period, observationId: oldObservation.id },
+ { ...context, plan: "oss" },
+ ),
+ ).resolves.toMatchObject({ id: oldObservation.id });
+
+ await expect(
+ handleGetObservation(
+ {
+ ...period,
+ observationId: oldObservation.id,
+ toStartTime: new Date(now - 35 * 24 * 60 * 60 * 1000).toISOString(),
+ },
+ limitedContext,
+ ),
+ ).rejects.toThrow(/not found within the supplied period/i);
+ });
+
it("should fetch an observation with an in-app agent context", async () => {
const { context, projectId } = await createMcpTestSetup();
const observation = createObservationEvent({
@@ -2549,7 +2761,7 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleGetObservation(
- { observationId: observation.id, fields: ["id"] },
+ { ...observationWindow, observationId: observation.id, fields: ["id"] },
{ ...context, inAppAgent: { permissions: "read" } },
)) as Record<string, unknown>;
@@ -2574,7 +2786,11 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
const result = (await handleGetObservation(
- { observationId: observation.id, fields: ["id", "metadata"] },
+ {
+ ...observationWindow,
+ observationId: observation.id,
+ fields: ["id", "metadata"],
+ },
context,
)) as Record<string, unknown>;
@@ -2594,7 +2810,7 @@ describe("MCP Read Tools", () => {
const observationId = randomUUID();
await expect(
- handleGetObservation({ observationId }, context),
+ handleGetObservation({ ...observationWindow, observationId }, context),
).rejects.toThrow(new RegExp(`Observation ${observationId} not found`));
});
@@ -2609,7 +2825,10 @@ describe("MCP Read Tools", () => {
await createEventsCh([observation]);
await expect(
- handleGetObservation({ observationId: observation.id }, context2),
+ handleGetObservation(
+ { ...observationWindow, observationId: observation.id },
+ context2,
+ ),
).rejects.toThrow(/not found/i);
});
});
diff --git a/web/src/features/mcp/server/observations/tools/getObservation.ts b/web/src/features/mcp/server/observations/tools/getObservation.ts
index abdc20fd9c..c37efeb92d 100644
--- a/web/src/features/mcp/server/observations/tools/getObservation.ts
+++ b/web/src/features/mcp/server/observations/tools/getObservation.ts
@@ -6,6 +6,7 @@ import {
} from "@langfuse/shared/src/server";
import { defineTool } from "../../../core/define-tool";
import { runMcpTool } from "../../../core/run-mcp-tool";
+import { clampToDataAccessDays } from "@/src/features/entitlements/server";
import {
ExpandMetadataKeysSchema,
getMetadataExpansionForProjection,
@@ -15,8 +16,14 @@ import {
projectObservation,
} from "../schema";
+const OBSERVATION_MAX_RANGE_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
+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 }),
fields: ObservationFieldsSchema,
expandMetadataKeys: ExpandMetadataKeysSchema,
});
@@ -26,19 +33,45 @@ 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.",
"",
'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.',
].join("\n"),
action: "traces:read",
baseSchema: GetObservationBaseSchema,
- inputSchema: GetObservationBaseSchema,
+ inputSchema: GetObservationBaseSchema.refine(
+ (input) => {
+ const rangeMs =
+ new Date(input.toStartTime).getTime() -
+ new Date(input.fromStartTime).getTime();
+ return rangeMs > 0 && rangeMs <= OBSERVATION_MAX_RANGE_MS;
+ },
+ {
+ message:
+ "getObservation requires fromStartTime before toStartTime with a maximum range of 90 days.",
+ path: ["toStartTime"],
+ },
+ ),
handler: async (input, context) => {
return await runMcpTool({
spanName: "mcp.observations.get",
context,
attributes: { "mcp.observation_id": input.observationId },
fn: async (span) => {
+ const dataAccessWindow = clampToDataAccessDays({
+ plan: context.plan,
+ fromTimestamp: input.fromStartTime,
+ });
+ if (
+ dataAccessWindow.accessFloor &&
+ dataAccessWindow.accessFloor >= new Date(input.toStartTime)
+ ) {
+ throw new LangfuseNotFoundError(
+ `Observation ${input.observationId} not found within the supplied period (${input.fromStartTime} to ${input.toStartTime}).`,
+ );
+ }
+
const projectionFields = getProjectionFields(input.fields);
const fieldGroups = getProjectionFieldGroups(projectionFields);
@@ -47,31 +80,42 @@ export const [getObservationTool, handleGetObservation] = defineTool({
"mcp.field_groups": fieldGroups.join(","),
});
- const items = await getObservationsV2FromEventsTableForPublicApi({
- projectId: context.projectId,
- page: 0,
- limit: 1,
- fields: fieldGroups,
- advancedFilters: [
- {
- type: "stringOptions",
- column: "id",
- operator: "any of",
- value: [input.observationId],
+ const items = await getObservationsV2FromEventsTableForPublicApi(
+ {
+ projectId: context.projectId,
+ traceId: input.traceId,
+ fromStartTime:
+ dataAccessWindow.effectiveFromTimestamp?.toISOString(),
+ toStartTime: input.toStartTime,
+ page: 0,
+ limit: 1,
+ fields: fieldGroups,
+ advancedFilters: [
+ {
+ type: "stringOptions",
+ column: "id",
+ operator: "any of",
+ value: [input.observationId],
+ },
+ ],
+ expandMetadataKeys: getMetadataExpansionForProjection(
+ projectionFields,
+ input.expandMetadataKeys,
+ ),
+ },
+ {
+ clickhouseSettings: {
+ max_execution_time: MCP_OBSERVATIONS_MAX_EXECUTION_TIME_SECONDS,
},
- ],
- expandMetadataKeys: getMetadataExpansionForProjection(
- projectionFields,
- input.expandMetadataKeys,
- ),
- });
+ },
+ );
const observation = items.find(
(item) => item.id === input.observationId,
);
if (!observation) {
throw new LangfuseNotFoundError(
- `Observation ${input.observationId} not found`,
+ `Observation ${input.observationId} not found within the supplied period (${input.fromStartTime} to ${input.toStartTime}).`,
);
}
diff --git a/web/src/features/mcp/server/observations/tools/listObservations.ts b/web/src/features/mcp/server/observations/tools/listObservations.ts
index f56e6e865e..6342ab9dbb 100644
--- a/web/src/features/mcp/server/observations/tools/listObservations.ts
+++ b/web/src/features/mcp/server/observations/tools/listObservations.ts
@@ -50,13 +50,7 @@ const ObservationCursorSchema =
"Cursor returned by a previous listObservations call",
);
-const EXPENSIVE_OBSERVATION_ACCESS_COLUMNS = new Set([
- "input",
- "output",
- "metadata",
-]);
-
-const EXPENSIVE_OBSERVATION_MAX_RANGE_MS = 14 * 24 * 60 * 60 * 1000;
+const OBSERVATION_MAX_RANGE_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
const EXPENSIVE_OBSERVATION_MAX_IO_LIMIT = 50;
const MCP_OBSERVATIONS_MAX_EXECUTION_TIME_SECONDS = 25;
@@ -293,8 +287,8 @@ 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 }).optional(),
- toStartTime: z.iso.datetime({ offset: true }).optional(),
+ fromStartTime: z.iso.datetime({ offset: true }),
+ toStartTime: z.iso.datetime({ offset: true }),
filter: z
.array(ObservationMcpFilterBaseSchema)
.optional()
@@ -314,43 +308,16 @@ const ListObservationsInputSchema = ListObservationsBaseSchema.extend({
type ListObservationsInput = z.infer<typeof ListObservationsInputSchema>;
-// Initially, we return io/metadata in full only if some limits are set
-const assertAllowedExpensiveObservationAccess = (
+const assertAllowedObservationAccess = (
input: ListObservationsInput,
projectionFields: string[],
) => {
- const expensiveColumns = new Set<string>();
-
- for (const field of projectionFields) {
- if (EXPENSIVE_OBSERVATION_ACCESS_COLUMNS.has(field)) {
- expensiveColumns.add(field);
- }
- }
-
- for (const filter of input.filter ?? []) {
- if (EXPENSIVE_OBSERVATION_ACCESS_COLUMNS.has(filter.column)) {
- expensiveColumns.add(filter.column);
- }
- }
-
- if (expensiveColumns.size === 0) return;
-
- if (!input.fromStartTime || !input.toStartTime) {
- throw new InvalidRequestError(
- `Accessing observation ${Array.from(expensiveColumns)
- .sort()
- .join(
- ", ",
- )} requires both fromStartTime and toStartTime with a maximum range of 14 days.`,
- );
- }
-
const rangeMs =
new Date(input.toStartTime).getTime() -
new Date(input.fromStartTime).getTime();
- if (rangeMs <= 0 || rangeMs > EXPENSIVE_OBSERVATION_MAX_RANGE_MS) {
+ if (rangeMs <= 0 || rangeMs > OBSERVATION_MAX_RANGE_MS) {
throw new InvalidRequestError(
- "Accessing observation input, output, or metadata by date requires a maximum range of 14 days.",
+ "listObservations requires fromStartTime before toStartTime with a maximum range of 14 days.",
);
}
@@ -374,7 +341,7 @@ export const [listObservationsTool, handleListObservations] = defineTool({
"",
'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.',
- "Requests that project or filter input, output, or metadata must include both fromStartTime and toStartTime with a date range of at most 14 days, even when scoped by traceId or observation id. Input/output projections support a maximum limit of 50.",
+ "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.",
].join("\n"),
action: "traces:read",
baseSchema: ListObservationsBaseSchema,
@@ -389,7 +356,7 @@ export const [listObservationsTool, handleListObservations] = defineTool({
fn: async (span) => {
const projectionFields = getProjectionFields(input.fields);
const fieldGroups = getProjectionFieldGroups(projectionFields);
- assertAllowedExpensiveObservationAccess(input, projectionFields);
+ assertAllowedObservationAccess(input, projectionFields);
const dataAccessWindow = clampToDataAccessDays({
plan: context.plan,
fromTimestamp: input.fromStartTime,