Tool Design, MCP, and Agent Context · Topic 1 of 2
Progressive Disclosure for MCP Tools and Agent Skills
Databricks Context Engineer: stage MCP tool discovery to cut tokens versus raw schema dumps, and move rarely used instructions into on-demand Agent Skills.
- 6 min
- A raw tool dump costs every schema on every call; staging costs summaries plus the selected schemas.
- Progressive disclosure also reduces wrong tool choice, not just tokens.
- Distinct tool metadata is what lets discovery surface a single tool.
What it is
Progressive disclosure means the agent sees a little about every capability first and the full detail only for the capability it chooses. For tools, that means names and short summaries up front, and a full schema only after selection.
The opposite is a raw tool dump: every tool's full description and parameter schema placed in the context on every call. The same idea applies to instructions: rarely used procedures move out of the system prompt into Agent Skills that load only when relevant.
How it works
Why raw tool dumps are expensive
An MCP server lists its tools with a name, a description and an input schema. If the client passes all of them to the model, the cost is paid on every call, used or not.
Worked numbers: an MCP server exposes 60 tools whose full schemas average 400 tokens.
| Approach | Tokens per model call | Over 20 calls |
|---|---|---|
| Raw dump of all 60 schemas | 60 x 400 = 24,000 | 480,000 |
| 60 names with 25-token summaries, plus 2 selected schemas | 1,500 + 800 = 2,300 | 46,000 |
The staged approach uses about a tenth of the tokens, and fewer detailed schemas also means less context confusion.
What enters the window at each stage
| Stage | What enters context | What stays out |
|---|---|---|
| Discovery | Tool names and one-line summaries, or a search tool that returns matching names | Parameter schemas, examples |
| Selection | The summaries of the few candidates that match the intent | All unrelated tools |
| Schema load | The full schema of the chosen tool only | Schemas of the tools not chosen |
| Execution | The call and its arguments | Any further tool detail |
| Result | Only the fields the step needs (tool result scoping) | Full raw payloads |
Tool metadata must be distinct, so discovery can match the user's intent to a single tool. Results should be scoped, so a 5,000-row query does not flood the window when the step needs three numbers.
If near-duplicate tools all match at discovery, every one of their schemas gets loaded and the saving is lost. The fix is distinct capability descriptions so only the best match is surfaced, not ranking after all candidates are already in context.
Scoping on Databricks
Databricks managed MCP servers exist for Unity Catalog functions, Genie spaces, Databricks AI Search and Databricks SQL, and external or custom MCP servers can also be connected. Connect only the servers an agent needs. The managed endpoint for Unity Catalog functions names the catalog, schema and function in its URL, so connecting only the needed functions is a first filter.
Agent Skills for rarely invoked capabilities
A system prompt is paid for on every call. Long instructions for capabilities used in a small share of requests waste most of that cost and can distract the model on ordinary requests.
Agent Skills follow an open standard: each skill is a folder with a SKILL.md file whose front matter gives a name and a description, plus optional scripts and reference files. Genie Code, the Databricks assistant, supports them and loads a skill when the request matches its description.
The loading strategy that minimizes baseline cost:
- Keep only each skill's name and description in the context at start.
- Load the full
SKILL.mdinstructions when a request matches the description. - Load the skill's extra files only when the instructions call for them.
Good candidates and poor candidates:
| Package as a skill | Keep in the system prompt |
|---|---|
| Rare, self-contained procedures (quarterly filing format, refund exception handling) | Rules that apply to every turn (safety, governance, persona, output format) |
| Long reference material for one task type | Capabilities used in most requests |
| Specialist workflows with their own scripts | Short instructions that cost little |
Worked numbers: a 9,000-token system prompt holds 6,500 tokens for five capabilities used in 3% of requests. Moving them to skills with about 30 tokens of description each leaves a baseline of 2,500 + 150 = 2,650 tokens. To protect task success, the descriptions must say clearly when each skill applies, and an MLflow evaluation set should confirm the success rate holds after the move.
How the exam asks about this
- "An agent connected to an MCP server with 80 tools spends most of its tokens on tool schemas." Use progressive disclosure: summaries first, full schema only for the selected tool.
- "Four overlapping order tools are all surfaced at discovery." Give each distinct capability metadata so discovery surfaces one best match.
- "The system prompt carries long instructions for a yearly audit report used twice a year." Package it as an Agent Skill loaded by its description.
What to remember for the exam
- A raw tool dump costs every schema on every call; staging costs summaries plus the selected schemas.
- Progressive disclosure also reduces wrong tool choice, not just tokens.
- Distinct tool metadata is what lets discovery surface a single tool.
- Scope tool results to the fields the step needs.
- Agent Skills keep name and description in context and load full instructions on demand.
- Keep always-on rules in the system prompt; move rare, self-contained procedures to skills.
Ranking or filtering tools after their full schemas are loaded does not save context. The tokens are spent as soon as the schemas enter the window.
Common mistakes
Moving core rules into skills. Safety, governance and output rules must apply on every turn. If they load only on a match, some requests run without them.
Writing vague skill descriptions. The description is the only thing the agent sees before loading. If it does not say when the skill applies, the skill is not loaded and task success drops.
Merging distinct tools to hide ambiguity. One generic tool loses the distinctions the agent needs. Fix the descriptions so each tool's purpose is clear.
Check yourself
Why does staged tool discovery use fewer tokens than loading all schemas?
Only names and short summaries are in context for every tool, and a full schema enters only for the tool selected, instead of every schema on every call.
Which instructions are good candidates for Agent Skills?
Rarely invoked, self-contained capabilities such as a once-a-quarter report procedure, not rules that must apply on every turn.
What loading strategy keeps baseline cost low without losing task success?
Keep only each skill's name and a clear description in context and load the full instructions when a request matches, then confirm success rate with evaluation.
Topic 1 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.