Skip to content

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

fix(mcp): Update observation tool descriptions to discourage FTS (#19217)

Ben Bachembaf2f3c39d6a
diff --git a/web/src/features/mcp/server/observations/tools/getObservation.ts b/web/src/features/mcp/server/observations/tools/getObservation.ts
index c548f6c08a..5b3fdf503c 100644
--- a/web/src/features/mcp/server/observations/tools/getObservation.ts
+++ b/web/src/features/mcp/server/observations/tools/getObservation.ts
@@ -39,7 +39,7 @@ export const [getObservationTool, handleGetObservation] = defineTool({
"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 (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.',
+ 'By default this returns compact summary fields. After reviewing listObservations summaries, request full input/output only for selected observations that need closer inspection. Pass specific field names to limit the response size; fields: ["*"] returns the full observation.',
'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",
diff --git a/web/src/features/mcp/server/observations/tools/listObservations.ts b/web/src/features/mcp/server/observations/tools/listObservations.ts
index 23a1846027..646f7303fc 100644
--- a/web/src/features/mcp/server/observations/tools/listObservations.ts
+++ b/web/src/features/mcp/server/observations/tools/listObservations.ts
@@ -342,10 +342,10 @@ export const [listObservationsTool, handleListObservations] = defineTool({
description: [
"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.",
+ "Prefer structured filters such as trace, name, type, level, and environment, combined with narrow time ranges. Use input/output/metadata content search only when matching that content is necessary to answer the user's question. 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 (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.',
+ 'Start with the default compact summary fields, then use getObservation to fetch full input/output only for selected observations that need closer inspection. Pass specific field names to limit the response size; fields: ["*"] returns the full observation.',
'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 (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"),