What you will be able to do
- Explain why an agent's choice between two tools depends on their descriptions rather than their names or implementations
- Spot the shared capability clause that makes two MCP tool descriptions ambiguous, using the Genie One and Databricks SQL MCP servers as the worked case
- Tell apart a description that says only what a tool does from one that also says when to use it instead of a neighbouring tool
- Apply a side-by-side method to two confused descriptions and name the rule that would separate them
Key concept
Description as the selection signal — When an agent decides which tool to call, the description (or docstring) is the only natural-language guidance it has about when each tool applies. If two descriptions share the same capability language and neither says when to pick the other, the agent has no basis for choosing, so it confuses them.
1.What the agent actually reads when it picks a tool
Suppose an agent keeps calling the wrong one of two tools. Before you can find the cause, you need to know what information the agent has when it chooses. It does not read your server code. It does not know which team built which tool or what a tool's name was meant to suggest. It decides from the text the tool advertises about itself.
Databricks tells you to discover tools at runtime instead of hardcoding them, because "Every MCP Service exposes a different set of tools." So what reaches the agent is a list of names, descriptions, and input schemas. The name is short and the schema covers argument types. The description is the one place that says in plain language what the tool does and when it applies.
The Databricks docs say the same about tools you write yourself. If you host your own MCP server, each tool needs a docstring because agents use it "to understand when to call the tool." If you build a Unity Catalog function tool, the toolkit parses its Google-style docstring, and you should write clear descriptions "to help the LLM understand how and when to use the function."
Note the word *when*. A description has two jobs: say what the tool does, and say when to use it. Ambiguous selection usually comes from a pair of descriptions that do the first job well and skip the second, so both describe the same capability and neither marks a boundary.
Checkpoint 1 of 7· Check yourself
A team finds that their agent mixes up two custom MCP tools. One engineer proposes renaming the tools; another proposes rewriting their docstrings. Based on how Databricks describes tool selection, which change targets what the agent uses to decide when to call a tool?
The docs say outright that agents use the docstring to understand when to call a tool. A new name alone leaves the shared description text, which is the source of the ambiguity, unchanged.
“Each tool must include a docstring. Agents use the docstring to understand when to call the tool.”Source: docs.databricks.com
2.A real overlap: Genie One versus the Databricks SQL MCP server
Databricks offers two managed MCP servers that are easy to confuse, and they make a good case study. Read each server's description of what it does, ignoring any guidance on when to use it.
| Server | Capability as described | Shared ground |
|---|---|---|
| Databricks SQL MCP server | Lets agents run AI-generated SQL against your Unity Catalog tables to read and write data | SQL executed against governed Unity Catalog data |
| Genie One MCP server | Genie searches your enterprise data, writes SQL, and returns an answer grounded in Genie Ontology | SQL executed against governed Unity Catalog data |
Here is the overlap. Both descriptions say an agent can get SQL run against your data. Both respect Unity Catalog permissions. Both run asynchronously: the SQL server's agent "calls the tool to start a query, then polls until the response completes", and Genie returns a response that the agent polls. If a user asks "what were last quarter's sales by region?", either capability statement plausibly fits. An agent comparing the two descriptions finds the same words in both, so it has no basis for choosing one.
The docs do not separate them by capability. Neither server is presented as more powerful. The dividing line is where the SQL comes from and what kind of request it is:
- The SQL server is for "running a specific query you or your coding agent wrote, inspecting schemas, validating SQL syntax, and authoring data pipelines." Its selling point is that "It gives you deterministic control over the exact SQL that runs." - Genie One is for "business questions asked in natural language, where accuracy depends on understanding what your data means." Genie "resolves business terms, metric definitions, and table relationships through Genie Ontology, your governed semantic layer."
The docs then write the rule in both directions. The SQL server's page says that for analytics questions in natural language, use Genie One instead. Both pages say to use the SQL server "when you need to run a specific query you already wrote." That is the kind of sentence missing from a pair of descriptions an agent keeps confusing: a when-not clause that names the neighbouring tool.
| Request looks like… | Route to | Why, per the docs |
|---|---|---|
| A business question in natural language | Genie One MCP server | Business terms are resolved through Genie Ontology, the governed semantic layer |
| A specific query someone already wrote | Databricks SQL MCP server | Deterministic control over the exact SQL that runs |
| Validating SQL syntax or authoring a pipeline | Databricks SQL MCP server | Named as development and data engineering use |
Checkpoint 2 of 7· Match them up
Match each request to the server the Databricks docs route it to, and the reason the docs give
Tap a term, then the definition that fits it.
Natural-language business questions go to Genie One, which resolves business terms and metric definitions. Already-written SQL, syntax checks and pipeline work go to the SQL server.
“For analytics use cases, where a user asks a business question in natural language, use the Genie One MCP server instead.”Source: docs.databricks.com
Checkpoint 3 of 7· Exam question
An agent has access to two MCP tools registered on the same Unity AI Gateway: - transfer_funds: "Moves money between two accounts for a customer." - process_payment: "Moves money from a customer account to complete a transaction." The agent repeatedly calls process_payment when a user asks to move savings into checking, and calls transfer_funds when a user asks to pay a bill. What is causing the ambiguous tool selection?
Correct answer: A — Both descriptions open with "Moves money ... account" and never state that one covers internal transfers while the other covers external bill payments.
- A. Correct. The shared opening phrasing and shared verb describe the same generic action without ever stating the distinguishing purpose (moving money between a customer's own accounts vs. paying a third party), so the model has no textual signal to separate the two use cases.
- B. Incorrect. Currency handling isn't mentioned in either description and isn't what the scenario shows failing — the confusion is about which tool matches internal transfers vs. bill payments, not currency support.
- C. Incorrect. The scenario describes overlapping natural-language descriptions, not identical parameter schemas; shared parameter names don't cause an LLM to merge two distinct tool entries in a function-calling list.
- D. Incorrect. Tool selection by an LLM is driven by semantic matching against the description text, not alphabetical order or name-prefix fuzzy matching of tool identifiers.
3.Overlap within one server, and a description that settles it
Overlap can also occur between tools on the same server. The Genie One MCP server exposes five tools. Read their descriptions as an agent would, side by side.
| Tool | Description |
|---|---|
| genie_ask | Ask Genie a natural-language data question and start a response. Returns conversation_id, response_id, and status. |
| genie_poll_response | Fetch the latest state of an in-flight or completed response, including progress steps, the final answer, and deep links. |
| genie_get_query_result | Fetch the full SQL result, including column schema and rows, for a query Genie ran. |
| genie_cancel_response | Request cancellation of an in-flight Genie turn. |
| view_ask | Ask Genie a question and open the interactive View. Offered instead of genie_ask to MCP Apps clients, and preferred when available. |
The two Fetch tools share a verb, but their objects differ. One fetches the *state of a response*: progress steps, final answer, deep links. The other fetches the *full SQL result*: column schema and rows. Because the descriptions name different things being fetched, the shared verb causes little ambiguity.
The two Ask tools are a real overlap. Both start a Genie answer to a question, so the shared action is their core purpose. The only difference is that view_ask opens the interactive View, an MCP App panel that "shows Genie's progress, visualizations, and final answer as the conversation unfolds." Databricks settles the ambiguity inside the description text itself: view_ask is "Offered instead of genie_ask to MCP Apps clients, and preferred when available." That one clause names the competing tool, the condition (an MCP Apps client), and the precedence (preferred). Compare that with a hypothetical pair described only as "Ask Genie a question" and "Ask Genie a question with a view", where the agent would have to guess.
The same pattern applies between servers. The Genie One page names a neighbouring server and gives the condition for choosing it: "To scope analytics to one curated Genie Agent, use the Genie Agent MCP server." Here the distinguishing dimension is scope (the whole workspace versus one curated agent), and the description says so.
Checkpoint 4 of 7· Check yourself
A reviewer says that genie_ask and view_ask overlap so much that one should be deleted. What does the view_ask description already do that removes the ambiguity?
The description includes an explicit substitution rule naming the other tool, the client condition and the preference. That is what separates two tools with the same core action.
“Offered instead of genie_ask to MCP Apps clients, and preferred when available.”Source: docs.databricks.com
Checkpoint 5 of 7· Exam question
A retail support agent has two MCP tools: - search_products: "Finds matching entries for a query." - search_faqs: "Finds matching entries for a query." When a customer asks a product-availability question, the agent sometimes calls search_faqs instead of search_products. What in the tool descriptions is driving this ambiguous selection?
Correct answer: A — Both descriptions say the tool "finds matching entries for a query" without naming the data source, so intent can't map to catalog vs. FAQ content.
- A. Correct. Neither description states what is being searched (the product catalog vs. the FAQ knowledge base), so the two tools read as functionally identical to the model, which then has to guess.
- B. Incorrect. A shared parameter name affects how arguments are supplied, not whether the model can distinguish which tool's purpose matches the user's intent — the failure here is in the description text, not the schema.
- C. Incorrect. Verb tense in a description has no bearing on how many tools an LLM is willing to select from; this isn't a documented mechanism of tool-selection ambiguity.
- D. Incorrect. Being hosted on the same MCP server does not merge Unity Catalog permission scopes or tool identities; each registered tool retains its own description and access control entry.
Sources5
4.A method for diagnosing two confused descriptions
The two cases above suggest a repeatable diagnosis. Databricks frames the goal like this: "Good documentation helps your agents know when and how to use each tool." When an agent consistently confuses two tools, check each description for both halves of that sentence.
1. Put the two descriptions side by side exactly as the agent receives them from tool discovery. 2. Strike out the shared phrases. With Genie One and the SQL server, "SQL" against "your data" or "Unity Catalog tables" goes. With genie_ask and view_ask, "Ask Genie a question" goes. 3. Read what remains. If only capability wording is left (more adjectives about the same action), you have found the overlap: neither description gives the agent a boundary. 4. Name the discriminating dimension. In the Databricks examples it is who wrote the SQL (a person or coding agent versus Genie from a natural-language question), which client is connected (MCP Apps or not), or scope (whole workspace versus one curated Genie Agent). 5. Check that the dimension appears as a when or when-not clause, ideally naming the other tool, as view_ask names genie_ask and the SQL server page names Genie One.
This matters because small wording changes have large effects. A Databricks blog on agent harnesses warns that "Small changes to how tools are described or called may cause the model to use them incorrectly." Shared phrasing between two descriptions is one such small detail.
Specificity also helps on its own. Databricks contrasts a well-documented Unity Catalog function with one that "lacks important details, making it harder for agents to use the tool effectively." The good example states its input and what it returns, scoped to "a specific customer":
CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
customer_name STRING COMMENT 'Name of the customer whose info to look up.'
)
RETURNS STRING
COMMENT 'Returns metadata about a specific customer including their email and ID.'Precise inputs and outputs, which Databricks lists as "Clearly define expected inputs and outputs", narrow each description. Precision alone does not remove overlap, though. Two precise descriptions of the same capability still collide, as the Genie One and SQL server capability statements show. The decisive fix in every Databricks example is a usage boundary, not more capability detail.
Checkpoint 6 of 7· Check yourself
Two custom MCP tools are described as "Runs SQL queries on sales tables and returns results" and "Queries sales data using SQL and returns rows with column names." The agent keeps confusing them. Which diagnosis fits the method above?
Remove the shared phrases and only capability wording remains, with no when or when-not boundary. Databricks frames good documentation as telling agents when, not just how, to use each tool.
“Good documentation helps your agents know when and how to use each tool.”Source: docs.databricks.com
Checkpoint 7 of 7· Exam question
A travel assistant agent has two tools: - get_current_weather: "Provides weather information for a specified location." - get_weather_forecast: "Provides weather information for a specified location." Asked "what will the weather be like this weekend?", the agent sometimes invokes get_current_weather instead of get_weather_forecast. What overlap in the descriptions explains this?
Correct answer: A — Both descriptions promise "weather information for a location" without stating whether it's the present moment or a multi-day forecast.
- A. Correct. The two descriptions are word-for-word identical in scope and neither mentions a time horizon, so nothing in the text tells the model that one tool answers 'right now' and the other answers 'in the coming days.'
- B. Incorrect. The scenario gives no indication of the required input format, and an input-format mismatch would cause a call error, not a wrong-tool selection between two available options.
- C. Incorrect. Missing units would affect how the response is interpreted after a tool runs, not which of two tools the agent chooses to call in the first place.
- D. Incorrect. Response format is unrelated to tool selection, which happens before either tool is invoked based on the description text alone.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Giving two confused tools more distinctive names will stop the agent mixing them up.Why is that wrong?
Agents rely on the description or docstring to decide when to call a tool. If two descriptions share the same capability language, renaming leaves that overlap in place.
Covered in What the agent actually reads when it picks a tool
2.Genie One and the Databricks SQL MCP server are separated by capability, with one able to run SQL and the other not.Why is that wrong?
Both get SQL run against Unity Catalog data. The docs separate them by request type: natural-language business questions go to Genie One, already-written queries go to the SQL server.
Covered in A real overlap: Genie One versus the Databricks SQL MCP server
3.Adding more detail about what each tool does will fix the overlap between two confused descriptions.Why is that wrong?
Two detailed descriptions of the same capability still collide. Descriptions need to say when to use the tool, which is how Databricks separates its own overlapping tools.
Covered in A method for diagnosing two confused descriptions
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Call tools/list (or DatabricksMCPClient.list_tools()) to get each tool's name, description, and input schema.”
↩︎ What the agent actually reads when it picks a tool“Every MCP Service exposes a different set of tools”
↩︎ What the agent actually reads when it picks a tool - 2.
“Agents use the docstring to understand when to call the tool.”
↩︎ What the agent actually reads when it picks a tool“Agents use the docstring to understand when to call the tool.”
↩︎ Key concept“Agents use the docstring to understand when to call the tool.”
↩︎ Exam trap 1“Each tool must include a docstring. Agents use the docstring to understand when to call the tool.”
↩︎ Checkpoint - 3.
“to help the LLM understand how and when to use the function”
↩︎ What the agent actually reads when it picks a tool“Good documentation helps your agents know when and how to use each tool.”
↩︎ A method for diagnosing two confused descriptions“lacks important details, making it harder for agents to use the tool effectively”
↩︎ A method for diagnosing two confused descriptions“Clearly define expected inputs and outputs.”
↩︎ A method for diagnosing two confused descriptions“Write clear descriptions for your function and its arguments to help the LLM understand how and when to use the function.”
↩︎ Exam trap 3 - 4.
“lets agents run AI-generated SQL against your Unity Catalog tables to read and write data”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“the agent calls the tool to start a query, then polls until the response completes”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“running a specific query you or your coding agent wrote, inspecting schemas, validating SQL syntax, and authoring data pipelines”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“It gives you deterministic control over the exact SQL that runs.”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“Use the Databricks SQL MCP server when you need to run a specific query you already wrote”
↩︎ Exam trap 2“For analytics use cases, where a user asks a business question in natural language, use the Genie One MCP server instead.”
↩︎ Checkpoint - 5.
“Genie searches your enterprise data, writes SQL, and returns an answer grounded in Genie Ontology”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“business questions asked in natural language, where accuracy depends on understanding what your data means”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“resolves business terms, metric definitions, and table relationships through Genie Ontology, your governed semantic layer”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server“Offered instead of genie_ask to MCP Apps clients, and preferred when available.”
↩︎ Overlap within one server, and a description that settles it“shows Genie's progress, visualizations, and final answer as the conversation unfolds”
↩︎ Overlap within one server, and a description that settles it“To scope analytics to one curated Genie Agent, use the Genie Agent MCP server.”
↩︎ Overlap within one server, and a description that settles it - 6.
“Use the Databricks SQL MCP server when you need to run a specific query you already wrote”
↩︎ A real overlap: Genie One versus the Databricks SQL MCP server - 7.https://www.databricks.com/blog/ai-harnessSecondary source
“Small changes to how tools are described or called may cause the model to use them incorrectly”
↩︎ A method for diagnosing two confused descriptions