Back office ops · Production

CloudQuery builds MCP server connecting Claude and Cursor to cloud infrastructure database: lessons learned on tool descriptions, context windows, and LLM behavior

The problem

When CloudQuery wired Claude and Cursor into their cloud infrastructure database via an MCP server, sparse tool descriptions caused the LLM to hallucinate table schemas, ignore tools entirely, or misinterpret their purpose; a single schema dump could also consume nearly the entire context window.

First attempt

Initial terse tool descriptions caused Claude to call tools sparingly or skip them; a tool named 'example_queries' was never invoked during two weeks of testing despite explicit prompting.

Workflow diagram · grounded in source
1
User queries via Claude or Cursor
trigger
“gives Claude or Cursor direct access to our cloud infrastructure database”
2
LLM selects tools from descriptions
ai_action
“The LLM reads the descriptions we provide for these tools and decides, on its own, when and how to invoke them to help answer the user's question.”
3
Schema output filtered for context
integration
“We built a filtering mechanism into the MCP server that strategically trims schema output before handing it to the LLM. We used Go with regular expressions and column ranking heuristics to discard irrelevant or redundant columns: - Alway…”
4
Sequential discovery pipeline
ai_action
“RECOMMENDED WORKFLOW (use these tools in sequence before executing queries): 1. First, use "list-installed-plugins" to see what data sources are available (aws, gcp, azure, github, kubernetes, etc.) 2. Then, use "table-search-regex" to f…”
5
SQL query executed
output
“Finally, use this tool to execute your crafted ClickHouse SQL query”
Reported outcome

After rewriting tool descriptions with domain-specific detail, embedding explicit workflow sequences, renaming tools, and filtering schema output, token usage dropped by about 90%, and Claude could handle over 20 table schemas simultaneously instead of choking after 3 to 4.

Reported metrics
Token usage reduction after schema filtering90%
Table schemas handled simultaneously after fixover 20 table schemas at once rather than choking after 3 to 4
Tool description character count changeincreased from ~50 to ~400
Tool selection accuracy improvement with richer descriptions (cited research)~30% on average
Show all 6 reported metrics
token usage reduction after schema filtering90%
table schemas handled simultaneously after fixover 20 table schemas at once rather than choking after 3 to 4
tool description character count changeincreased from ~50 to ~400
tool selection accuracy improvement with richer descriptions (cited research)~30% on average
tool invocation frequency reduction for ambiguous names (cited research)>40%
tool usage before fix during testing periodnot once during two weeks of testing
Reported stack
ClaudeCursorClickHouse
Source
https://www.cloudquery.io/blog/mcp-server-gotchas-we-learned-the-hard-way
Read source ↗

Frequently asked questions

What did this team achieve with this AI workflow?

After rewriting tool descriptions with domain-specific detail, embedding explicit workflow sequences, renaming tools, and filtering schema output, token usage dropped by about 90%, and Claude could handle over 20 tabl…

What tools did this team use?

Claude, Cursor, ClickHouse.

What results were reported?

Token usage reduction after schema filtering: 90%; Table schemas handled simultaneously after fix: over 20 table schemas at once rather than choking after 3 to 4; Tool description character count change: increased from ~50 to ~400; Tool selection accuracy improvement with richer descriptions (cited research): ~30% on average (source-reported, not independently verified).

What failed first in this deployment?

Initial terse tool descriptions caused Claude to call tools sparingly or skip them; a tool named 'example_queries' was never invoked during two weeks of testing despite explicit prompting.

How is this back office ops AI workflow structured?

User queries via Claude or Cursor → LLM selects tools from descriptions → Schema output filtered for context → Sequential discovery pipeline → SQL query executed.

Related back office ops cases