Agent Skills vs MCP tools: what goes where

An MCP tool is code an agent calls: it takes a typed input, does the work and returns a result that is the same every time. An Agent Skill is a SKILL.md file an agent reads: it describes a process, a policy or a judgement call in plain language. Use a tool when the result has to be exact. Use a skill when the agent needs to know how your team does things. Most real workflows need both, with the skill naming the tools.

We serve both through one MCP connection, so we get asked which one a piece of work should become almost every week. This is the split we use.

##What each one is

A tool has a name, a description, an input schema and a function that runs. In MCP the agent sees the name, description and schema, decides to call it, and gets back whatever the function returns. Tool annotations such as readOnlyHint tell the client whether a call changes anything, so it can decide when to ask the person first.

A skill is a folder with a SKILL.md: YAML frontmatter with a name and a description, then instructions, plus optional reference files. The format is the open Agent Skills specification. Agents load skills in layers. At the start they see only each skill's name and description, they read the body when a task matches, and they open the reference files only if the body points to them. That is why a team can publish many skills without filling every conversation with them.

##The short answer

• Make it a tool when the answer must be exact and repeatable: numbers, lookups, anything that touches a database or an API.
• Make it a tool when it needs credentials. A skill is text the agent reads, so it has nowhere safe to keep a token.
• Make it a skill when it is judgement, order or policy: what to check first, when to escalate, how the report should read.
• Make it a skill when it changes often and the people who own it do not write code.
• Make it both when a process uses data. The skill says what to do and names the tools, the tools do the exact parts.

##Signs something should be a tool

The clearest sign is an agent getting the same thing slightly different on different days. If you ask for last week's refunds and the total depends on which query the model happened to write, the query belongs in code. A tool with a strict schema also refuses bad input before anything runs, and the agent reads that error and corrects itself, which is easier to trust than a plausible wrong number.

The second sign is size. When a workflow pulls thousands of rows to compute three numbers, the agent pays for every row that passes through its context. A tool can do the aggregation and return only the three numbers.

##Signs something should be a skill

If the thing you keep correcting is how the agent works rather than what it computes, write a skill. Typical examples are the order of checks before a refund, which numbers a weekly report leads with, the tone of a customer reply, or who owns which part of the codebase. None of it needs code, and all of it is knowledge one person on the team has and the others do not.

Skills also suit teams without engineers. A project in Zenitya can publish only skills, so an operations or finance team can keep its playbooks in a repository and change them through pull requests.

##How they work together

Here a support team handles refunds for late orders. Two tools do the exact parts: orders.findLateOrders returns orders that missed their promised date, and orders.refund issues a refund. The skill holds the policy:

---
name: refund-late-orders
description: Use when a customer asks for a refund on a late order. Covers when to refund and when to escalate, using orders.findLateOrders and orders.refund.
---

1. Check the delivery date with `orders.findLateOrders`. If the order is not late,
   explain the promised date and stop.
2. Up to 5 days late: refund shipping with `orders.refund`.
3. More than 5 days late, or an order over 500 EUR: do not refund. Escalate to
   the support lead with the order ID and the days late.

Full policy and edge cases: [policy](references/policy.md).

The tools never change when the policy does, and the policy never has to explain how to query the order system. Refer to tools by their full name in the skill, because the agent uses that name to call them.

##Mistakes we see most

• A procedure written into a tool description. The description should say what the tool does, when to use it and what it returns. Steps across several tools belong in a skill.
• Arithmetic in a skill. If the skill says to sum the rows and compare with last month, the model does the maths itself every time. Put the calculation in a tool.
• A vague skill description. Agents pick a skill by its description alone, so it should name the situations it covers, not only the topic.
• API keys or connection strings inside a skill. Anything an agent reads can end up in its output. Keep credentials as tool secrets.

##Sharing both with a team

Tools and skills are only useful to a team if everyone has the same versions. In Zenitya both deploy from your repositories with zya deploy, and both are granted to groups of people, service accounts and chat channels. Every agent connected to https://api.zenitya.com/mcp sees the tools of its groups and reads their skills through list_skills and load_skill, whether it runs in Claude, ChatGPT, Cursor or a cloud job. When a skill changes, the next request uses the new version.

##Questions people ask

##Further reading

• Agent Skills: Specification
• Anthropic: Equipping agents for the real world with Agent Skills
• Model Context Protocol: Specification: Tools
• Zenitya docs: Publishing skills