[jaegermcp] Improve MCP tool descriptions#8314
Merged
jkowall merged 4 commits intoApr 15, 2026
Merged
Conversation
Clarify what each tool returns vs. what it omits, so agents can make informed decisions from tool metadata alone: - search_traces: lightweight summaries without spans or attributes - get_span_details: verbose OTLP output per span - get_trace_errors: truncation behavior via total_error_count - get_trace_topology: does not include attributes, events, or logs - get_critical_path: self_time_us identifies the bottleneck Signed-off-by: Roshan Singh <rosh.s568@gmail.com> Signed-off-by: Roshan <rosh.s568@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the human-readable MCP tool descriptions for the Jaeger MCP server so agents/clients can make better decisions using tool metadata alone (part of #7827, follow-up to #8311).
Changes:
- Expanded the
Descriptionstrings for the 8 registered MCP tools to clarify intent, output “weight”, and runtime behaviors (e.g., truncation, time formats). - Added more detailed explanations for topology and critical path tools to help agents choose appropriate calls.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- OTLP spans have events, not logs. Fixed in topology description. - self_time_us indicates where time is concentrated, not a definitive bottleneck label. Softened in critical path description. Signed-off-by: Roshan Singh <rosh.s568@gmail.com> Signed-off-by: Roshan <rosh.s568@gmail.com>
yurishkuro
reviewed
Apr 10, 2026
yurishkuro
reviewed
Apr 10, 2026
yurishkuro
reviewed
Apr 10, 2026
- Remove trailing period from get_span_names description - Add 'etc.' to search_traces field list - Remove time format hint from search_traces (parameter specs belong in schema) - Remove 'OTLP' from get_span_details and get_trace_errors descriptions Signed-off-by: Roshan Singh <roshansingh7890@gmail.com> Signed-off-by: Roshan <rosh.s568@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8314 +/- ##
=======================================
Coverage 95.87% 95.87%
=======================================
Files 320 320
Lines 16873 16883 +10
=======================================
+ Hits 16177 16187 +10
Misses 541 541
Partials 155 155
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
yurishkuro
approved these changes
Apr 14, 2026
yurishkuro
added
the
changelog:experimental
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Apr 14, 2026
## Which problem is this PR solving? - Part of #7827 Follow-up to feedback on #8311: tool descriptions should be self-sufficient so agents can make informed decisions from tool metadata alone, without relying on external prompts or instructions. The current descriptions are minimal one-liners that don't clarify what each tool returns vs. what it omits. An agent reading the current descriptions cannot distinguish a lightweight call (topology) from a verbose one (span details), or know that error results may be truncated. ## Description of the changes Improved descriptions for all 8 MCP tools. Each description now states: - What the tool does - What distinguishes its output (lightweight vs verbose, what data is included vs omitted) - Runtime behavior the schema cannot express (truncation, time format hints) No workflow ordering or cross-tool sequencing was added. The input/output schemas already encode parameter dependencies (e.g. service_name required in search_traces). **1 file changed, string-only modifications. No logic changes.** ## How was this change tested? - `go test ./cmd/jaeger/internal/extension/jaegermcp/...` - all passing - `make lint` - 0 issues - `make fmt` - clean - Descriptions are strings with no runtime effect; existing tests validate tool behavior unchanged. ## Checklist - [x] I have read https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md - [x] I have signed all commits - [x] I have added unit tests for the new functionality - [x] I have run lint and test steps successfully: `make lint test` ## AI Usage in this PR (choose one) - [x] **Light**: AI provided minor assistance (formatting, simple suggestions) --------- Signed-off-by: Roshan Singh <rosh.s568@gmail.com> Signed-off-by: Roshan <rosh.s568@gmail.com> Signed-off-by: Roshan Singh <roshansingh7890@gmail.com> Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com>
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which problem is this PR solving?
Follow-up to feedback on #8311: tool descriptions should be self-sufficient so agents can make informed decisions from tool metadata alone, without relying on external prompts or instructions.
The current descriptions are minimal one-liners that don't clarify what each tool returns vs. what it omits. An agent reading the current descriptions cannot distinguish a lightweight call (topology) from a verbose one (span details), or know that error results may be truncated.
Description of the changes
Improved descriptions for all 8 MCP tools. Each description now states:
No workflow ordering or cross-tool sequencing was added. The input/output schemas already encode parameter dependencies (e.g. service_name required in search_traces).
1 file changed, string-only modifications. No logic changes.
How was this change tested?
go test ./cmd/jaeger/internal/extension/jaegermcp/...- all passingmake lint- 0 issuesmake fmt- cleanChecklist
make lint testAI Usage in this PR (choose one)