Skill vs tool vs MCP server

Read these first

• Writing a skill
• When MCP is the wrong answer

What you will know

• Choose correctly between the three for a real requirement

  Classify whether the missing capability is durable guidance, an executable interface, or an externally operated integration, including who controls its lifecycle.

• Trace a request through ownership and deployment

  A reviewer should be able to identify where code, credentials, releases, failures, and audit responsibility reside for each option.

• Convert something from one form to another and say what improved

  The migration should expose trade-offs such as portability, latency, authorization, observability, and whether the model still receives the necessary procedural context.

• Build a small requirement using a skill plus a tool, then remove one and record the failure

  The experiment should demonstrate that guidance can shape invocation while execution still requires a callable, permissioned interface.

• Justify the choice to a reviewer

  A sound decision accounts for operational burden, trust boundaries, change ownership, and the cost of choosing an externally controlled dependency.

Chapters

1. 1

   A well-formed call is not a correct decision

   A support agent with a clean `issue_refund(order_id, amount_cents, reason_code)` tool refunds outside the 30-day window and refunds shipping on damaged goods, and every call validates. Execution and judgement are separate capabilities: the tool permits action, the skill supplies the policy the model reasons with before acting. Data retention has the same shape — category rules as a skill, deletion and anonymisation as tools — and removing either half shows you which.

   Read chapter
2. 2

   Where the credential lives decides more than where the code lives

   A skill holds no secret at all — it is text. A tool runs inside your agent process with whatever that process holds. A server holds its own, so the agent presents an identity and never sees the downstream credential. Trace code, credentials, releases, failure handling and audit responsibility for one capability in all three shapes; the single environment fact that decides tool versus server falls out of that trace.

   Read chapter
3. 3

   A schema encodes which fields exist, never what a good one contains

   Moving `search_tickets` out of three agent processes into one server genuinely buys a single maintained deployment and a credential that lives with its operator. Converting a change-request skill the same way does not: a typed `create_change_request` cannot encode when a CAB review is warranted or what a strong justification looks like. Delete the skill and every call still validates, which is why the regression is invisible. Report the rest of the ledger with it: the hop the conversion adds to every call, and the fact that what the capability did is now visible only in the operator's logs rather than in your own traces.

   Read chapter
4. 4

   A vendor's changelog entry is a deploy into your agent

   A field renamed in a server's response and a new required argument, announced where nobody reads, degraded an agent silently for two days. Choosing an externally operated integration is choosing to let someone else change your behaviour with no diff in your repository. Judge that class of dependency on lifecycle control — versioning, deprecation policy, whether you can pin — rather than on whether the capability works today.

   Read chapter
5. 5

   Splitting one server into four fixes coupling and not context

   A single server exposing 40 tools across Jira, GitHub, Slack and deploys produces two complaints that look like one: definitions crowding the window, and a Slack outage taking down ticket filing. Splitting by domain fixes the second and leaves the first exactly where it was, since forty definitions cost the same from four servers. Know which change addresses which, and what to keep as a server regardless.

   Read chapter
6. 6

   The window is freed by cutting definitions, not deployments

   The context half of that complaint is answered by shrinking the interface: expose a subset of tools per agent or per task rather than everything the servers offer, collapse fine-grained calls into fewer coarse ones with a mode argument, put the rarely used long tail behind a discovery step instead of a resident definition, and delete the tools that exist because someone enumerated an API rather than because an agent needs them. When a reviewer objects that splitting means four deployments instead of one, answer on the other axis — a deployment is a recurring cost you can price and staff, while one server fronting four systems means any one of them can take the other three down with it.

   Read chapter
7. 7

   The reviewer needs to know what crosses the boundary in both directions

   Defending a third-party server means stating what leaves your side — arguments, and often surrounding request content — and what it may return into the model's context, since a careless dependency both leaks and instructs. It also means pricing operational burden and change ownership. That is the argument that beats 'anything touching an external system is a server', a rule that mandates a deployment and an on-call rotation per single-consumer integration.

   Read chapter