query_graph tool description gets truncated by MCP clients, hiding the DSL grammar (#553) · Issues · GitLab.org / orbit / GitLab Knowledge Graph

query_graph tool description gets truncated by MCP clients, hiding the DSL grammar

## Summary The `query_graph` MCP tool description embeds the full condensed DSL schema. Several MCP clients silently truncate tool descriptions, so the model only ever sees the first slice of that schema. Models on those clients miss the DSL grammar, fall back to guessing field names, and hammer `get_graph_schema` to recover. Move the DSL grammar out of the description and behind a tool call. ## What we are seeing Across editor sessions on Claude Code, agents repeatedly: - Invent query field names that are not in the DSL (`type` instead of `query_type`, missing `traversal` wrapper, etc.). - Re-call `get_graph_schema` after every failure, because the failure messages are clearer than what the description gave them. - Behave correctly on clients that pass the description through unchanged (OpenCode, direct gRPC). Inspecting the registered tool description on the affected clients shows it ending with a truncation marker partway through the TOON `$defs` block. The DSL body that documents `traversal`, `aggregation`, `path_finding`, `NodeSelector`, and `Filter` is not in the visible portion. ## Where the size comes from The tool description is built as `base_description + "\n\nQuery DSL Schema:\n<toon>\n" + condensed_query_schema() + "\n</toon>"`. The condensed schema is currently around 18 KB by the test that pins it under 19 KB. Total description is about 18 KB. Common client caps are roughly an order of magnitude smaller. Source: - [registry.rs#L50-76](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/crates/gkg-server/src/tools/registry.rs#L50-L76) - [schema.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/main/crates/gkg-server/src/tools/schema.rs) ## Proposal 1. Drop the inline TOON from `query_graph`'s description. Keep the base sentence and one line that points at a tool returning the grammar. 2. Either extend `get_graph_schema` with a flag that returns the DSL grammar, or add a small `get_query_dsl` tool that returns the same TOON the description currently embeds. 3. Keep the size test on the condensed schema so the grammar stays compact, but the upper bound stops being load-bearing once it is no longer in a description field. Cost: one extra tool call the first time the model writes a query in a session. That is the same shape `get_graph_schema` already uses for entity discovery, so the pattern is familiar to the model. <details> <summary>Why not just shrink the schema further</summary> The 2 KB ceiling some clients enforce is well below what the DSL needs to be useful as a single-shot reference. Even an aggressive trim would leave the description fragile to any future field. Putting the grammar behind a tool call removes the size constraint entirely and lets the description stay short and stable. </details> <details> <summary>Out of scope</summary> - Changing client behaviour. We cannot rely on every MCP client passing arbitrarily large descriptions through. - Reformatting the TOON output itself. The condensed format is fine; only its location is the problem. </details> Relates to gitlab-org&21852.

issue