Foundations domain 2 · Tool design and MCP integration
Tool descriptions and errors
- The model chooses tools from their descriptions. Say what the tool does, what input it expects (with an example), what it returns, and when not to use it. Two tools with near-identical descriptions get confused.
- Too many tools on one agent degrades selection. Split them across specialised agents, and give an agent a single extra read-only tool if it frequently needs one from another role.
- Errors should be structured and actionable. Say whether a retry can help, what category of failure it was, and what to do instead. Tell "no results" apart from "the search failed".
See also: Professional domain 3 · Capability bloat and progressive discovery.
MCP primitives: who controls what
| Primitive | Controlled by | What it is |
|---|---|---|
| Tools | The model | Actions the model decides to call. Something executes. |
| Resources | The application | Readable content (catalogues, reference data) made available as context. Nothing executes. |
| Prompts | The user | Templated messages a person picks, often shown as slash commands |
- Elicitation: the server asks the user for input (not the model).
- Sampling (the server asks the client's model for a completion) and roots (the client tells the server which paths are in scope) are client features.
MCP servers in Claude Code
| Scope | Who gets it | Where it lives |
|---|---|---|
| Local (the default) | Just you, in this project | ~/.claude.json |
| Project | Everyone who clones the repository | .mcp.json, committed |
| User | Just you, in all your projects | ~/.claude.json |
| Managed | Everyone, set by the organisation | Managed settings |
A shared server that needs a per-person credential: project scope plus environment variable expansion (${VAR}) in .mcp.json. The configuration is shared; the secret isn't.
See also: Professional domain 3 · Authentication and authorisation.
tool_choice
auto: the model decides whether to call a tool.any: it must call a tool, and picks which.tool(named): it must call that tool.none: no tool calls.disable_parallel_tool_uselimits a turn to one tool call.tool_choiceis a Messages API parameter, not a Claude Code setting. In Claude Code, you enforce behaviour with the tools you grant or deny, permission modes, hooks and descriptions.
any or a named tool. Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1 reject forced tool_choice with an error. On those models, use auto with strict tool use, or structured outputs, and enforce ordering in code. Haiku 5.5 still accepts a forced call, but the response starts with the tool call and has no thinking block.See also: Foundations domain 4 · Prompt engineering and structured output.
Built-in tools
Read, Write, Edit, Bash, Grep and Glob. Use Grep to search file contents, Glob to match file paths, Edit for a targeted change to part of a file, and Read with an offset and limit for a slice of a large file.
See also: Exam guide vs today · Foundations (CCAR-F).
Docs: Defining toolsStrict tool useMCP server featuresMCP transportsMCP deprecationsMCP in Claude CodeTools reference
Practise Domain 2