Task statement 8.3 · Tools and MCPs

8.3 · Agentic Customization

Shelfwise, the course example, gives its agent one capability beyond the model: stock_lookup, served by its own MCP server. Agentic customization is choosing that shape on purpose from built-in tools, custom tools, Skills and MCP servers, by what each one costs and who else needs it.

Why it's tested

The tempting design gives every capability its own MCP server, or pastes every instruction into the prompt. A server built for one application adds a process to deploy and secure that nobody else uses. Instructions that only some requests need cost context on every request. Both designs overlook a built-in tool that may already do the job.

KnowledgeBuilt-in tools, custom tools and MCP servers

Built-in tools ship with the platform, so you enable them instead of writing them. Claude Code and the Agent SDK provide tools such as Read, Edit, Bash and WebFetch (1.2), and the Claude API offers server tools such as web search and web fetch, which Anthropic runs (8.1). They are general-purpose, so none of them knows your private systems' operations, credentials or rules: Bash could call an internal API, but nothing describes or maintains that access. A custom tool is an action your own code performs, described to Claude by a name, a description and a schema. On the Claude API it is a user-defined client tool. In the Agent SDK you write it with @tool and serve it with create_sdk_mcp_server, which builds an MCP server inside your own process.

A standalone MCP server is a separate program that any MCP client can connect to, such as Claude Code, Claude Desktop, the Agent SDK or the MCP connector (8.2). It suits a capability that several applications or people need, maintained in one place, and its price is a process to deploy, secure and version. Every tool definition costs context on each request, although Claude Code and the Agent SDK defer MCP tool schemas through tool search (8.1) by default.

KnowledgeSkills

A Skill adds know-how rather than access. It is a folder holding a SKILL.md file of instructions, with optional scripts and reference files, and it loads in stages. Its name and description, about 100 tokens, sit in context from the start, so Claude can match a task to it. The body loads only when Claude or a user invokes the Skill, and other files load only when read. A script runs through the session's own tools, and only its output enters context. A Skill is therefore a cheap home for a procedure or reference that some requests need, and instructions that every request needs belong in the system prompt instead (6.2). Each surface finds Skills in its own way, and custom Skills do not sync between surfaces:

Claude Code

Folders in .claude/skills/ (project) or ~/.claude/skills/ (personal). Each also runs as /name, and command files now work as Skills. disable-model-invocation: true keeps a Skill's description out of context until someone types it.

Agent SDK

Read from the same folders through setting_sources, or from a path through the plugins option, and invoked with the built-in Skill tool, so an explicit tools list must name "Skill". The skills option limits which ones Claude may invoke.

Claude API

Named by skill_id in the request's container, beside the code execution tool, whose container has no network. Anthropic ships pptx, xlsx, docx and pdf; custom Skills upload to the workspace through the Skills API.

KnowledgeChoosing for a use case

Choosing the appropriate approach for a use case starts from what Claude is missing. When the platform already does the job, enable the built-in tool, because nothing is cheaper to maintain. When Claude lacks a procedure or reference that only some tasks need, write a Skill. When Claude must act on your code or systems, write a tool, and let the number of clients decide where it lives: inside one application as a custom tool, or in an MCP server once other applications or Claude Code sessions need it. In the guide's example, an internal inventory service with a REST API must be reusable across several Claude applications and maintained apart from each, so an MCP server exposes its operations as tools and each application connects to it. The options also combine, and the docs pair an MCP server, which provides the connection, with a Skill that teaches Claude how to use it well.

Interactive · four ways to add a capability

A decision table with four columns, built-in tool, custom tool, MCP server and Skill, and six rows. Pick it when: the platform already does it, such as search, fetch or files; one application's own code that no other client needs; several clients need it, maintained in one place; know-how that some requests need, not every request. Runs in: the harness, or Anthropic for server tools; your application, in process in the Agent SDK; the server's own process over stdio or HTTP; Claude follows it, running scripts through Bash. Who can reuse it: any application, as shipped, but it knows none of your systems' operations; this application only, so reuse means copying it; every MCP client, applications and Claude Code; one surface at a time, by folder, upload or plugin. Context cost: each enabled definition, so remove unused ones; its definition, unless tool search defers it; its tools' definitions, which tool search can defer; about 100 tokens while idle, with the body only when used. Upkeep: none, Anthropic maintains it; your code and tests, shipped with the application; a service to deploy, authorise and version; Markdown to edit, with no service to run. Shelfwise: no built-in tools, tools equals an empty list; no in-process tool, which would serve one client; stock_mcp serves stock_lookup; no Skills, setting_sources equals an empty list. PICK IT WHEN RUNS IN WHO CAN REUSE CONTEXT COST UPKEEP SHELFWISE Built-in tool the platform does it SEARCH, FETCH, FILES the harness or API SERVER TOOLS: ANTHROPIC any app, as shipped NOT YOUR SYSTEMS' OPS each enabled schema REMOVE UNUSED ONES none: enable it ANTHROPIC MAINTAINS IT none tools=[] Custom tool one app's own code NO OTHER CLIENT NEEDS IT your application IN PROCESS IN THE SDK this app only COPY IT TO REUSE IT its definition TOOL SEARCH CAN DEFER your code and tests SHIPS WITH THE APP not in process WOULD SERVE ONE CLIENT MCP server several clients MAINTAINED IN ONE PLACE its own process STDIO OR HTTP every MCP client APPS + CLAUDE CODE its tools' schemas TOOL SEARCH CAN DEFER a service to run DEPLOY, AUTHORISE stock_mcp stock_lookup Skill know-how, sometimes NOT EVERY REQUEST Claude follows it SCRIPTS VIA BASH one surface each FOLDER, UPLOAD, PLUGIN ~100 tokens idle BODY ONLY WHEN USED Markdown to edit NO SERVICE TO RUN none setting_sources=[]

Choose an option to read its column.

Built-in tool: the platform already has the action, so you enable it and write nothing. Claude Code and the Agent SDK ship tools such as Read, Edit, Bash and WebFetch, and the Claude API's server tools, such as web search, run on Anthropic's side. None of them knows your private systems. Shelfwise enables none: tools=[] keeps every built-in definition out of Claude's context.

Custom tool: your own code runs the action, described by a name, a description and a schema. In the Agent SDK, @tool and create_sdk_mcp_server serve it inside your process, so only that application can call it. Shelfwise did not build stock_lookup this way, because engineers also need the tool in Claude Code.

MCP server: a separate program that any MCP client can connect to, so applications and Claude Code sessions share one maintained copy, at the cost of a process to deploy and secure. Shelfwise's stock_mcp serves stock_lookup to the service and to each engineer's Claude Code.

Skill: a SKILL.md folder of instructions, scripts and reference files. About 100 tokens of name and description stay in context, and the body loads when the Skill is invoked. It adds know-how, not access. Shelfwise loads none: setting_sources=[] skips .claude/skills/, and every staff question needs the stock rules, which stay in the system prompt.

Each column is one option; read down the criteria. The blue row is what Shelfwise uses.

KnowledgePlugins: the packaging layer

A plugin (2.5) installs Skills, subagents, hooks and MCP servers as one unit, which is how a choice made in one repository reaches others. Writing one means a directory, usually with a manifest at .claude-plugin/plugin.json, whose required name becomes the prefix of each Skill, as in /release-kit:notes. The components sit at the plugin root, beside .claude-plugin/, never inside it. You load it for one session with claude --plugin-dir ./release-kit, check it with claude plugin validate, and publish it through a marketplace. 2.5 covers installing plugins and their scopes. A plugin that needs another plugin lists it under dependencies (2.6).

release-kit/
├── .claude-plugin/plugin.json   # {"name": "release-kit", "version": "1.2.0"}
├── skills/notes/SKILL.md        # runs as /release-kit:notes
├── hooks/hooks.json             # hooks on lifecycle events
└── .mcp.json                    # MCP servers started with the plugin

SkillWorked example: the stock rules as a Skill?

An engineer proposed moving Shelfwise's stock rules out of the system prompt into a stock-rules Skill, to slim the cached ≈6,000-token prefix. The team priced the idea on paper and rejected it. Every staff question is a stock question, so each chat would load the Skill through an extra Skill tool call. Its body would then arrive as a tool result inside that chat, not in the prefix that every chat reads from the cache. Claude also decides whether to invoke a Skill, so a chat could be answered without the rules. The service could not load or invoke it anyway, as its options show:

ClaudeAgentOptions(
    system_prompt=STOCK_RULES,         # every request needs them: kept, cached
    tools=[],                          # no built-in tools, so no Skill tool
    setting_sources=[],                # .claude/skills/ is never read
    mcp_servers={"stock": STOCK_MCP},  # the one custom tool
    allowed_tools=["mcp__stock__stock_lookup"])

The decision table above also explains stock_mcp. An in-process @tool would serve only the service, but each engineer also runs the server in Claude Code (8.2), so a separate stdio server is the one place where stock_lookup lives.

More precise than the guide. "Built-in tools" is the Claude Code and Agent SDK name for the tools that ship with the harness, such as Read, Bash and WebFetch (as of 2026-10-05). The Messages API docs sort tools by who runs them instead, as the box in 8.1 shows. Exam answer: a built-in tool is one the platform provides ready-made, so you enable it instead of writing it.

Before adding a capability, ask: what is Claude missing, and who else needs it? The platform already has the action → turn on the built-in tool. Instructions only some requests need → a Skill. Instructions every request needs → the system prompt. Access to your code or systems → a custom tool for one application, or an MCP server once other applications or clients need it.
Takeaway
  • In the Agent SDK a custom tool is an MCP server that runs in your process: @tool plus create_sdk_mcp_server, with nothing else to deploy.
  • A Skill brings no new access: its name and description cost about 100 tokens from the start, its body loads when invoked, and its scripts run through the session's own tools.
  • A plugin is the packaging layer: .claude-plugin/plugin.json names it, and that name prefixes its Skills (2.5).

check yourself

0 / 3 answered

A two-person team runs a Python app on the Claude API that writes briefings from public news articles. Users paste up to five article URLs, and Claude must read each article's text and cite it. The articles need no sign-in. The team wants the fewest moving parts to build, host and maintain.Which approach best meets the team's goal?

Select one.

A ferry operator's TypeScript Agent SDK service answers fare questions in a chat. The fare calculation is a function in the service's own code that reads a timetable the service keeps in memory. No other application and no Claude Code user needs it. The team wants Claude to call it without deploying or supervising a second process.Which approach best meets these needs?

Select one.

A finance team's backend calls the Messages API directly, with no agent harness. It must now return each monthly summary as an Excel workbook with a chart. The team wants Anthropic's maintained spreadsheet capability, not file-building code of its own, and will download each file with the Files API.Which TWO additions to the Messages request together meet this need?

Select two.

sources

  1. Claude Code Docs, "Extend Claude Code": built-in tools covering most coding tasks; Skills, MCP, hooks and plugins matched to goals; context cost by feature (Skill descriptions every request, MCP schemas deferred by tool search); MCP for the connection and a Skill for using it well; plugins as the packaging layer. Checked 2026-10-05.
  2. Claude Code Docs, "Extend Claude with skills" and "Tools reference": project and personal Skill folders; custom commands merged into Skills; disable-model-invocation; the built-in Skill, Read, Edit, Bash and WebFetch tools. Checked 2026-10-05.
  3. Claude Code Docs, "Extend agents with skills" and "Give Claude custom tools": Skills loaded through setting_sources; "Skill" in an explicit tools list; no programmatic Skill registration; @tool / tool() and create_sdk_mcp_server running in-process. Checked 2026-10-05.
  4. Claude Platform Docs, "Agent Skills" and "Using Agent Skills with the API": three loading levels and about 100 tokens of metadata; scripts' output only in context; container skills with the code execution tool; pptx, xlsx, docx, pdf; workspace-wide custom Skills; no sync across surfaces; no network in the API container. Checked 2026-10-05.
  5. Claude Platform Docs, "Tool use with Claude", "Web fetch tool" and "Code execution tool": user-defined and Anthropic-schema client tools versus server tools; web fetch as a server tool for URLs in the conversation; a container with no internet access. Checked 2026-10-05.
  6. Claude Code Docs, "Plugins overview" and "Create a plugin": plugin components; the .claude-plugin/plugin.json manifest and its required name as prefix; components at the plugin root; --plugin-dir; claude plugin validate; marketplaces. Checked 2026-10-05.
  7. Claude Certified Developer – Foundations exam guide, Domain 8 sample 3: an internal inventory REST service, reusable across several Claude applications, exposed through an MCP server.
  8. Shelfwise's rejected stock-rules Skill proposal, its options listing and the release-kit plugin are this course's additions.