D2 TS 2.1 · 2.2 · 2.3 · 2.4 · 2.5 · ~6 hrs · Skip to quiz →
A hook script sits in the scripts folder, well written and tested. It never fires. What is the first place to look?
Settings first, because settings say which hooks run; the scripts only say what hooks do. A script on disk with no registration is not connected to anything, and you will meet that exact shape again in this module.
A researcher agent reads forty files and sends its findings back to your main session. What actually crosses back into your window?
Only the report. The forty files and all the reasoning stay in the worker's own window, which is why the report contract (cite every claim, end with a Gaps line) matters so much.
▶ Watch: a tool description is a prompt · 3 min
When Claude "reads a file," what is actually happening: the model reaching into your disk, or something else?
Something else. The model cannot touch your disk. It sends a tool call, a request naming a tool and its input, and the harness (the Claude Code software) checks permissions, runs the hooks, executes the tool, and hands the result back.
A model on its own can only produce text. Everything else Claude Code does for you, reading files, searching, editing, running commands, happens through tools: named actions the harness offers to the model and executes on its behalf.
The agentic loop, with the tool step in bold:
The part that matters for this whole module is how the model picks a tool at step 3. It reads a menu: every tool's name and description, loaded into the context window. It never sees the code behind any of them. Name and describe a tool well and the model picks it at the right moments. Name it badly and the model guesses, and some of those guesses are wrong. Every rule in this module comes from that one fact.
Claude Code ships with a native toolbelt, and the six tools the exam names are Read, Write, Edit, Bash, Grep, and Glob. You have been watching all six work in every demo in this course. The next section teaches you to read them working, and what that changes about the way you ask.
The model decides a shell command should run. Which layer actually executes it?
The harness. The model only asks. Claude Code checks permissions, runs any matching hooks, and then executes, which is why your hooks and permission rules hold no matter what the model decides.
You never type Grep or Bash yourself, and Claude picks its own tools without asking. So what is the point of a consultant learning what they do?
Three things. The exam tests it directly. The tool names scroll past you in every session, and reading them tells you whether Claude is working well. And knowing what the tools can do changes what you ask for. This section covers all three.
Watch any session work and a quiet ticker runs past you: Grep, Read, Edit, Bash. Claude chose every one of those on its own, and it will keep choosing on its own. You are never the one picking. So this section is about reading the ticker, because that ticker is the closest thing you get to watching a colleague's screen while they work. Three reasons it earns your attention:
| Tool | What it does | When Claude reaches for it |
|---|---|---|
| Grep | Searches for text inside files | It knows a word or phrase that appears in the file |
| Glob | Finds files by name pattern | It knows the shape of the filename (*.md, 2026-08-*) |
| Read | Opens one file into the window | It knows which file and needs the contents |
| Edit | Changes a specific piece of one file | The file mostly stays; one part changes |
| Write | Creates a file or replaces one whole | The file is new, or nothing old survives |
| Bash | Runs a command in the terminal for you | A single command does what would otherwise take many steps |
Two consultants ask the same notes repo for the same fact. Watch both trails.
> look through the notes and tell me about vendor pricing
"Look through" gave Claude nothing to search for, so it opened files until it found the answer. All four files now sit in the context window for the rest of the session.
> find where the notes mention the rebate deadline
The prompt handed Claude a phrase it could search for. One search, one file opened, answer.
Same repo, same answer, and the difference was one phrase in the prompt. Give Claude something searchable and the trail gets short on its own.
You ask for one rule in your CLAUDE.md reworded. The file is 60 lines long. Two trails you might see for the exact same request:
> reword the file naming rule in CLAUDE.md so it says the date always comes first
One Edit, one line. You can review the change in five seconds, and the other 59 lines were never touched.
> reword the file naming rule in CLAUDE.md so it says the date always comes first
A full rewrite for a one line request. The rule changed, and every other line was rebuilt from scratch, so any of them could have changed too.
When you see the rewrite, ask about it, in plain words:
> that was a one line change. why did you rewrite the whole file instead of editing the one line?Claude either gives you a real reason or redoes it as an Edit. Asking that question is supervision, and it costs you one sentence.
Bash means the command line: the text window where typed commands operate the computer directly. You may never have opened it, and you never need to, because Claude types there for you. What it changes is the price of chores. Work that feels like an afternoon of clicking is often one typed line, and once you know that, you start asking for it.
> rename all the meeting notes in 30 Meetings so each filename starts with the date of the meeting, like 2026-08-14 pbm-renewal.md
Forty renames, one line in the trail, a few seconds on the clock.
| The chore, as you would ask for it | Done by hand | In the trail |
|---|---|---|
| "Rename all forty meeting notes so each starts with its date" | An afternoon, with forty chances for a typo | One Bash line, seconds |
| "Move the vendors folder into 20 Clients and keep its git history" | A drag and drop, with git left to guess what happened | One Bash line, history intact |
| "Delete every empty note in the inbox" | Opening each one to check it first | One Bash line |
| "Add the review header to every note from August" | Thirty copy and pastes | One Bash line |
The habit to build has nothing to do with commands. It is knowing these chores are cheap, so you ask for them instead of quietly doing them yourself, file by file.
You ask for all forty deliverable files to get this year's date prefix added to their names. Which trail should you expect to see?
One command. Renaming is what the terminal does in a single line, so forty of anything scrolling past is the signal to ask what is going on. And the useful half of knowing this: bulk renames are cheap, so you can ask for them without hesitating.
One line of settings.json needed a new value, and the trail shows Write replacing the entire file. What do you do?
Ask. An Edit gives you one small change to review; a full rewrite bets your hook registrations and permission rules on the reconstruction being perfect. Claude usually chooses well, and the trail is how you notice the day it does not.
None of this ever asks you to open the terminal or write a Bash command yourself. Claude does all the typing. Your part is to read the work the way you would read a junior colleague's approach, and to size your requests to what the hands can actually do. That is the whole skill, and the exam table comes free with it.
An engineer renames a tool from get_data2 to get_provider_roster and changes nothing else, and Claude starts picking it correctly. Why would a rename change behavior?
Because the name is most of what Claude sees. The model picks tools by reading their names and descriptions, so the rename rewrote the only evidence it had.
A skill's description decides whether the skill ever fires. Tools work exactly the same way, and the stakes are higher, because a wrongly picked tool acts. Four design rules, each doing real work:
get_member_claims tells anyone reading the menu what comes back. get_data2 tells them there was already a get_data and somebody gave up. The engineer who wrote the MCP server knows what each one does; the model is not that engineer. It is the new hire, on its first day, every session.In one sentence, your own words: why does this course keep saying a tool description is a prompt?
Because the model reads the description to decide when to use the tool, the description is instructions to the model, and instructions to the model are prompts. Writing "use this for questions about member billing" steers behavior exactly the way a line in CLAUDE.md does.
The test for any tool interface: could a smart person who has never seen the MCP server's code, reading only the menu, pick the right tool for a real request on the first try? If a person cannot, the model cannot, because the menu is all the model gets. And be clear about when you will use this test, because it is never while writing an MCP server. You will use it choosing between MCP servers, diagnosing why sessions keep failing against one, and handing a platform team the exact critique that fixes theirs. Menu reading is a consulting skill wearing technical clothes.
A tool call fails and the MCP server answers with exactly this: "Error 500." What does Claude do next, and what does that cost?
It retries, usually the same call, because the error told it nothing about what to change. Each blind retry costs a turn, tokens, and time, and it usually fails the same way.
When a tool call fails, the error message becomes the model's next input. The model reads it and decides what to do, which means the error message is a prompt too, and you get to write it. A dead end error and a teaching error, side by side:
Error 500member_not_found: no member with ID 99999.
Member IDs are 5 digits and start with 4.
Use search_members to look one up by name.The first says something broke. The second says what broke, what valid input looks like, and which tool to try instead, and a model that reads it corrects course on the very next call, with no human involved. The anatomy of an error worth returning:
The Model Context Protocol carries this pattern natively: a tool result can be marked as an error while still carrying readable content, so the explanation reaches the model instead of dead-ending in the plumbing. The reader an error actually has is the model, at two in the morning, with nobody to ask. Your use for this anatomy: when an automation keeps retrying against some system, read the error it is getting, and when a platform team asks what their MCP server should return on failure, hand them the four numbered lines above. That one page of advice is worth a support queue.
Three error messages for the same failed document lookup. Which one lets an unattended run recover?
The third. It names the failure, shows a valid ID, and points at the next tool. The second one looks structured but its only instruction is to find a human, which an unattended run cannot do.
The filing agent needs to move files. The research agent never does. What is the cost of giving both agents every tool anyway?
The research agent can now write, which means a confused research run can now damage files. Access nobody needs is risk nobody needed to take.
Every agent file carries a tools line at the top: the researcher reads and searches, the reviewer only reads. The principle behind those choices is least tools: every agent gets the tools its job requires and none beyond, for two reasons that compound.
MCP tools distribute the same way: an agent can be granted one MCP server's tools without inheriting every MCP server the repo knows.
tool_choice is the dial that controls how the model uses whatever menu it has. The vocabulary comes from the Claude API and the Agent SDK, and the exam tests it, so here it is straight:
| Setting | What it means |
|---|---|
auto | The model decides whether to use a tool at all. The default. |
any | The model must use some tool; answering in plain text is off the table. |
tool (a named one) | The model must use the specific tool you name. |
none | The model may not use tools; text only. |
When would anyone force a specific tool? When a step already knows the right move, so the model's judgment can only add variance. Picture a pipeline: an assembly line of automated steps, each one's output feeding the next, running with nobody watching. One step's entire job is "run the extraction tool on this document." Set tool_choice to that tool and the step has exactly one thing it can do, which is the point: a step with no choices cannot wander.
Inside Claude Code, the levers you actually hold are two you have already used: the agent file's tools line, and the permission rules underneath it as the locks. The tools line lives in the file's frontmatter, and since that is a strange word, here is everything it means: the small block at the top of a file, fenced by two lines of three dashes, where the file describes itself. From the researcher agent:
---
name: researcher
tools: Read, Grep, Glob
---
You are the team's researcher. Given a question
and a folder, read everything relevant...Everything between the dashed lines is the frontmatter. That tools line is the closest thing Claude Code gives you to tool_choice: it decides what the researcher may ever touch, before any session starts.
A nightly pipeline step must call the extraction tool on each intake document, every time, no judgment involved. Which tool_choice setting fits?
Name the tool. The step has no decision in it, so leaving one open just adds a way to be wrong. auto is for sessions where the model should judge; any still lets it pick the wrong tool confidently.
Your client's ticketing system has an API. Claude Code has no ticketing tool. What is the standard way to put that capability on Claude's menu?
An MCP server: a small program that speaks the Model Context Protocol, presents the ticketing actions as named, described tools, and plugs into Claude Code with one registration command.
MCP, the Model Context Protocol, is an open standard for connecting AI applications to outside capabilities. An MCP server is a small program that exposes tools, each with a name and a description, exactly the interface you learned to design earlier in this chapter: a name that says what the tool returns, a description that says when the tool is the right choice. The name and the description are all the model reads when it picks. Claude Code is a client: it connects to MCP servers, adds their tools to the menu, and calls them through the same permission and hook checks as every built-in.
Two facts keep newcomers oriented here. First: you connect to MCP servers other people built. You will almost never build one. Every major work platform now ships an official MCP server: Atlassian for Jira and Confluence, Slack, ServiceNow, Salesforce, GitHub, Notion, Sentry, Stripe, Figma. When a company needs an MCP server for one of its own internal systems, its platform engineering team builds it. Consultants like you connect to these MCP servers, vet them, and govern them. The closing demo practices exactly that, on real MCP servers.
Second: an MCP server is a running program, and only its menu entry looks like a skill. The menu now holds three kinds of things: the built-in tools from the start of this chapter, your skills, and MCP tools. Side by side:
| A skill | A built-in tool | An MCP tool | |
|---|---|---|---|
| What it is | A markdown file of instructions | A capability that ships inside Claude Code | A capability added by an MCP server, a separate program |
| An example | Your meeting-notes skill | Grep, Read, Edit, Bash | Atlassian's Confluence search |
| Who built it | You, for your own repo | Anthropic | Whoever published the MCP server: a vendor, Anthropic, or a client's platform team |
| What happens when Claude picks it | Claude reads the instructions and does the work itself, using its tools | Claude Code runs it on your machine | Claude sends the call to the MCP server; the MCP server does the work and hands back a result |
| What all three share | A name and a description on the menu, which Claude reads to decide when to reach for each | ||
Two ways an MCP server runs:
Three sources, in the order a consultant should reach for them:
The reviewed directory Look here first
Anthropic maintains a directory of connectors at claude.ai/directory. Listings are reviewed before they appear, though Anthropic is explicit that it does not security audit the MCP servers themselves.
For example: search the directory for Confluence and the listing that comes back is Atlassian's own connector. Slack, Notion, Figma, and Stripe are listed the same way, each entry pointing at the company's official MCP server.
Official vendor MCP servers The client-work default
The MCP server published by the company that owns the system, at that company's own address, with that company's sign-in. For a client engagement, official vendor or client built is the default rule, and it is a defensible one to say out loud in a meeting.
For example: Atlassian's MCP server lives at mcp.atlassian.com and signs you in with your own Atlassian account. GitHub and Sentry publish theirs the same way: the company's own web address, the company's own login. If the address belongs to anyone else, it is not the official MCP server.
Community directories Research only
Public registries list tens of thousands of MCP servers, and the overwhelming majority are unvetted code by unknown authors. Useful for research. Never the source for a client repo.
For example: search a public registry for Confluence and you get dozens of results with names like confluence-mcp and confluence-tools, written by authors you have never heard of. Any one of them might be fine. Nothing on the listing page tells you which, and that is the problem.
Connecting one is one ask, the same way you ask for anything else:
> connect the official atlassian MCP server for this project, so the whole team can reach jira and confluenceClaude writes the registration and confirms it. What appears in your repo: one new file, .mcp.json at the repo root, holding the MCP server's name and its address. This is what the repo looks like afterward, the way a code editor (VS Code) would show it, with the new file selected:
{
"mcpServers": {
"atlassian": {
"type": "http",
"url": "https://mcp.atlassian.com/..."
}
}
}The first time the MCP server needs your account, there is a sign-in. Type /mcp and your browser opens Atlassian's normal login page, the same one you use to open Jira on any morning. Sign in once and the MCP server keeps the credentials from then on. (For the terminal inclined, the same wiring is one command, claude mcp add --transport http plus the vendor's MCP server address, and it produces the identical registration. The prompt is the everyday road.)
Where the registration lives decides who gets it, the same question every file in a shared repo answers: who is the audience?
| Scope | Where it lives | Who gets the MCP server |
|---|---|---|
| local | your user config, tied to this project | you, in this repo (the default) |
| project | .mcp.json at the repo root, committed | every teammate who clones the repo |
| user | your user config | you, in every project |
These three sit on the same ladder the whole course uses for settings and rules: enterprise policy above everything (IT decides which MCP servers may run at all), the project level for the team, and the personal level for just you, which comes in two flavors, local (this repo) and user (every repo). For a shared second brain, project is the level that matters, and it is the one this chapter's demo uses. One honest detail: a project scoped MCP server does not run silently on a teammate's machine. Their first session asks them to approve it, once, and that is a feature. Nobody's Claude starts calling an outside system without them saying yes to it.
Commit that .mcp.json and the MCP server becomes part of the team's second brain: one teammate wires it, and everyone who clones the repo has the tools.
Inside a session, type /mcp to see every connected MCP server, the tools each one brought, and, for remote MCP servers that need an account, the sign in.
And when you ask a fresh session "what tools do you have here?", the MCP server's tools show up under long names. The name looks strange the first time, and it is only three pieces of information joined together:
mcp__atlassian__searchconnected through MCP · from this MCP server · this tool
Those long names exist so your permission rules can grab onto them. In the settings file, one line blocks a single tool, or a whole MCP server's worth, the same way a deny rule locks a secrets file:
{ "permissions": { "deny": [ "mcp__atlassian__getJiraIssue" ] } }One line, and that tool is off the menu for every session in this repo, no matter what any prompt asks for.
Both extend Claude Code, and they extend different layers:
| A plugin | An MCP server | |
|---|---|---|
| What it adds | Packaged instructions: skills, commands, agents, hooks | Live capabilities: tools that act on outside systems |
| Made of | Markdown and configuration | A running program |
| Reach for it when | The team's know-how should install as one bundle | Claude needs hands it does not have |
And they compose: a plugin can carry MCP server configuration inside it, so one install can deliver the firm's skills and the firm's tool connections together.
You register the official Atlassian MCP server in the committed .mcp.json. A teammate clones the repo tomorrow. What do they have to do to get the tools?
The registration itself traveled with the clone, because project scope is a committed file, the same way CLAUDE.md travels. What remains is the one-time approval: their first session asks before the MCP server runs, they say yes once, and the tools are on their menu. If the MCP server needs an account, they sign in with their own through /mcp. That is the difference between wiring a tool for yourself and wiring it for the team.
A teammate finds a community MCP server that connects to your consulting client's ticketing system. What three questions come before installing it?
Who wrote and maintains it? What data does it send, and where? What access would it hold? Until those have answers, it does not touch any repo used on a client engagement.
Security is the number one reason enterprises hesitate on MCP: in a late 2025 survey of 300 technical leaders, 64 percent named it the top obstacle, ahead of cost. The concerns have names now, and knowing them is part of the consultant's job:
Three enterprise facts follow, each a direct consequence:
For a healthcare practice, the current state is worth stating plainly, because your consulting clients will ask. The plumbing exists: open source MCP servers for FHIR (the healthcare data exchange standard) are real, and healthcare specific MCP extensions with privacy guardrails have been published. The big electronic health record vendors ship no MCP product yet, and publicly documented health plan production deployments are scarce. The honest advisory line: the pattern is proven in general enterprise, the healthcare specific pieces are early, and anything touching member data needs the same review as any system that touches member data, because tool results land in the context window.
The five consultant team at the regional health plan got their first integration request: wire the team's second brain into the plan's internal document platform, which already had an MCP server, built by the health plan's own engineers for an earlier pilot.
.mcp.json in the shared repo gave all five consultants the tools the same morning.The MCP server's menu: get_data, get_data2, and query_v3. The health plan engineer who built it knew exactly which was which. Nobody else did, including Claude. Asked for a policy document's history, sessions picked get_data when the answer lived behind query_v3, and the failures looked random: the same question worked Tuesday and failed Wednesday, depending on the guess.
The fix took one afternoon, and nobody touched the code that actually fetches documents. The team changed two things: what the tools are called, and what the errors say.
First, the menu. Each tool got a name that says what comes back, and a description that says when to reach for it:
| Old name | New name | New description |
|---|---|---|
get_data | get_document | "One document, fetched by its ID." |
query_v3 | get_document_history | "All versions and approvals for one document. Use for questions about how a document changed." |
get_data2 | search_documents | "Find documents by phrase or topic. Use when you do not have a document ID." |
Second, the errors. A failed lookup used to come back as a bare error that said nothing. Now it reads like this:
document_not_found: no document with ID POL-99.
Document IDs look like POL-2026-001. If you only
know the topic, use search_documents.Watch what those two changes did to a session. Before, a request like "pull the approval history for the telehealth policy" forced a guess between three unreadable names, and a wrong guess failed in a way that taught nothing, so Claude retried into the same wall. After, the same request lands on get_document_history, because the description says that is exactly what it is for. And on the days a lookup still fails, the error itself hands over the next move. Wrong tool picks stopped that week. The retry loops went with them, because recovery no longer needed a human to explain what went wrong.
Mid engagement, a teammate found a community MCP server that promised a slicker connection to the same document platform. It was one edit away from the shared .mcp.json, and remember what project scope means: commit that edit, and all five consultants are running the new MCP server by the next morning, with the health plan's document queries flowing through it.
Before the edit, the three questions that precede any MCP server got asked. Here is how this one did:
| The question | The answer they got |
|---|---|
| Who wrote it, and who maintains it? | A username. No organization behind it, no track record, nobody to call. |
| What data does it send, and where? | Nothing answered it. Every search query, and every document the tools returned, would pass through code nobody could vouch for, bound for an address nobody knew. This is the exact shape tool poisoning and rug pull attacks live in. |
| What access would it hold? | The same read access as the health plan's own MCP server, granted permanently. |
So the MCP server went to a disposable sandbox instead: an isolated environment with no health plan data, no credentials, and nothing worth protecting, where the team could watch what the MCP server actually did with a query before deciding anything.
Play the avoided path forward to see what that one day of caution bought. The edit ships on Monday. All week, five consultants ask the second brain about the health plan's policy documents, and every one of those questions travels through unvetted code with an unknown destination. If that destination turns out to be wrong, the next conversation with the health plan is about its document text leaving through a tool nobody approved. The sandbox route cost the team one day. The other path risked the engagement.
The near miss also produced the rule the engagement had been missing, written down the same week: MCP servers reach the shared repo from an approved list, and nothing else. The list lives at the policy level, so the answer to "can I just install this?" exists before anyone asks it.
You are the teammate who found that community MCP server, and it really does look better than the health plan's own. Pick your move, then read what follows from it. Try all three.
▶ Watch the demo: connecting your first MCP server · 4 min
The prompt pack: every demo prompt, cleaned and explained
The demo connects a real MCP server from the user's chair, in three parts. Part one finds and vets: where MCP servers come from, the official vendor default, and the three questions run against a real candidate. Part two connects: the plain English ask, the project scope registration with the level ladder, the browser sign in through /mcp, and the one time approval a teammate sees on their first session. Part three governs and proves: the new tools on the menu under their long names, a real question answered through the MCP server, the reminder that results land in the context window, and the break on purpose: pull the registration, watch the tools vanish, put it back.
Then run the pack in your own repo. The prompt pack linked above holds every prompt from the demo, cleaned up and explained. Copied as is or rephrased in your own words, check what the demo checked as you go:
Take the Module 06 quiz → then hit the Study App for Domain 2 reps.