Tool Design, MCP, and Agent Context · Topic 2 of 2
Tool Selection, Descriptions and Clearing Tool Outputs
Databricks Context Engineer: pick the right Unity Catalog tool, find the overlap in confused MCP tool descriptions, and choose raw tool outputs to clear.
- 5 min
- Choose a tool on functional fit, input and output compatibility, and the task's stated rules.
- Unity Catalog function and parameter comments are the descriptions the agent reads.
- Confusion comes from shared verbs, objects or scope in descriptions; make each one distinct.
What it is
An agent picks a tool by reading its name, description and parameter schema. If two descriptions overlap, it cannot tell them apart. Once a tool has run, its raw output sits in the history and keeps costing tokens.
This page covers three exam tasks: choosing the right Unity Catalog tool for a task, finding the overlap that confuses an agent, and deciding which old tool outputs can be cleared when the window fills.
How it works
Choosing a Unity Catalog tool
Unity Catalog functions become agent tools, and the function and parameter COMMENT text is what the model reads as the description. Judge each candidate on three things.
| Criterion | Question to ask |
|---|---|
| Functional fit | Does it do exactly what the task needs (read versus write, one record versus many, this domain)? |
| Input compatibility | Can the agent supply every required parameter, in the right type and format, from what it has? |
| Output compatibility | Does it return what the next step needs (a status, a list, a number) in a usable shape? |
| Task requirements | Does it respect stated rules: read-only, governed data, latency, scope of one customer? |
Worked case: the task is "tell the customer whether order ORD-10293 has shipped".
| Tool | Parameters | Returns | Verdict |
|---|---|---|---|
search_orders | customer_email STRING | All orders for a customer | Wrong input; the agent has the order ID, not the email |
get_order_status | order_id STRING | Current status of one order | Best fit: exact input and output |
update_order | order_id STRING, status STRING | Confirmation | Writes data; the task is read-only |
orders_summary | start_date DATE, end_date DATE | Counts by status | Aggregates, not one order |
A clear function comment makes the right choice easy for the model.
CREATE OR REPLACE FUNCTION main.support.get_order_status(
order_id STRING COMMENT 'Order ID, for example ORD-10293')
RETURNS STRING
COMMENT 'Returns the current shipping status of one order. Use when the user asks where a single order is.'
RETURN (SELECT status FROM main.support.orders WHERE id = order_id LIMIT 1);Finding the overlap in confused descriptions
When an agent keeps mixing up two tools, compare their descriptions part by part. The confusion comes from an overlap in one of these:
| Part | Overlapping example | Distinct version |
|---|---|---|
| Verb | "Gets customer information" and "Retrieves customer details" | "Returns contact details" versus "Returns billing history" |
| Object | Both say "customer data" | Name the exact record: profile versus invoices |
| Scope | Both say "for a customer" | One customer by ID versus all customers in a region |
| When to use | Neither says | "Use for address changes; not for payments" |
The overlap is usually a shared generic phrase ("customer data") that matches the same requests. Rewrite each description to state what it returns, its scope, and when to use it and when not to.
Which raw tool outputs to clear
In a deep history, old tool outputs are often the largest items. Clearing removes them, or replaces them with a short placeholder, without a model call. It is a form of trimming, cheaper than compaction.
| Clear it | Keep it |
|---|---|
| Outputs already consumed, whose key facts appear in a later message or decision | The latest output the agent is still working on |
| Large raw payloads: full query results, logs, page text | Outputs holding the only copy of a value later steps need, unless it was recorded elsewhere |
| Outputs superseded by a newer call to the same tool | User messages, stated constraints and decisions |
| Results that can be fetched again by calling the tool | Results that are expensive or impossible to reproduce |
Worked numbers: a window of 128,000 tokens holds 118,000 tokens, of which 70,000 are twelve old query results the agent already summarized. Clearing those eleven consumed outputs and keeping the current one drops usage to about 54,000 tokens, with nothing the next step needs lost.
A placeholder such as "result cleared, call run_sales_query again if needed" tells the agent how to get it back.
How the exam asks about this
- "The agent keeps calling get_customer_info when it should call get_customer_profile; both say they return customer data." The overlap is the shared object phrase; make each description state exactly what it returns and when to use it.
- "Pick a tool to cancel one subscription by ID." Choose the tool whose inputs match the ID the agent has and whose function is that single write, not a bulk or read-only tool.
- "The window is near capacity after 60 tool calls." Clear consumed, large or superseded raw outputs; keep the current output, user constraints and decisions.
What to remember for the exam
- Choose a tool on functional fit, input and output compatibility, and the task's stated rules.
- Unity Catalog function and parameter comments are the descriptions the agent reads.
- Confusion comes from shared verbs, objects or scope in descriptions; make each one distinct.
- Good descriptions say what the tool returns, its scope, and when not to use it.
- Clear consumed, bulky, superseded or easily reproduced tool outputs first.
- Never clear the active output, user constraints or decisions that later steps rely on.
Clearing an output whose value was never recorded elsewhere causes later steps to guess or repeat work. Record the needed facts first, then clear the raw output.
Common mistakes
Picking the tool with the closest name. A well named tool can still need inputs the agent lacks or return the wrong shape. Check the schema.
Renaming tools without changing descriptions. The model reads the description to decide. If both still say "returns customer data", the confusion stays.
Clearing the oldest messages first by default. Age alone is not the test. An early user constraint must stay; a recent but already consumed 20,000-token query result can go.
Check yourself
Two tools both describe themselves as "returns order information". Why does the agent confuse them?
The descriptions overlap on the same generic object and give no scope or usage boundary, so both match the same requests; distinct descriptions fix it.
Which tool outputs are the best candidates for clearing?
Large raw outputs the agent has already consumed and recorded, or that a newer call superseded, since removing them frees space without losing needed facts.
What three checks justify a Unity Catalog tool choice?
Functional fit with the task, compatibility of its inputs and outputs with what the agent has and needs, and the task's stated requirements such as read-only access.
Topic 2 of 2 in Tool Design, MCP, and Agent Context
Test yourself on Tool Design, MCP, and Agent Context
The full Databricks Context Engineer Associate question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Databricks. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.