jd five

Tools and Skills

An agent needs a way to reach outside the chat text. That way is a tool — also called a skill.

What a tool (skill) is

A tool (or skill) is a capability your program can run when the model asks for it. Same job, two common names.

Examples of tools / skills:

Tool / skill What your program actually does
Read a file Open a path on disk and return the text
Look up an order Call your shop API or query a database
Search the web Hit a search API and return snippets
Send a message Post to Slack, email, or a ticket system
Run a calculation Execute a function you trust (not “hope the model did the math”)

The bright line

The model stays on the server. It only sees text (and structured tool calls) in the request.

It does not grow hands. It cannot touch your laptop, your database, or your payment system by itself.

So:

  • The model chooses that a tool / skill is needed, and with what inputs
  • Your program runs that tool / skill
  • Your program puts the result back into the next request
  • The model continues with real data instead of guessing

If you skip the middle step, you do not have a tool — you only have more prose.

Worked example: notes.txt

Remember the open door from earlier: if someone asks “What is in my notes.txt?” and you never put the file in the request, the model can only guess.

With a read_file tool / skill, the trip can look like this:

  1. Person asks: “What is in my notes.txt?”
  2. Model replies in a way that means: “I need the read_file skill — path notes.txt.”
  3. Your program opens the file (the tool runs here, on your side)
  4. Your program sends the file text back to the model in a new request
  5. Model answers using that text
The model asks. Your code runs the skill.
  Person: "What's in notes.txt?"
            │
            ▼
       Server / model
            │
            │  need skill: read_file(path)
            ▼
       Your program  ── runs tool/skill ──▶  reads notes.txt
            │
            │  file text in next request
            ▼
       Server / model
            │
            ▼
       Useful answer (from real file contents)

What goes in and what comes out

A tool / skill almost always has a name, inputs, and a result. Those are usually data — often JSON — the same idea as structured outputs.

Model asks for the tool (shape idea — field names vary by company):

{
  "tool": "read_file",
  "inputs": {
    "path": "notes.txt"
  }
}

Your program runs it, then sends a result back (again as data):

{
  "tool": "read_file",
  "result": "Milk, eggs, buy cat food"
}

Or, if something failed:

{
  "tool": "read_file",
  "error": "file not found: notes.txt"
}

Model chooses the tool / skill. Your code executes it. Results go back into the conversation.

In code you usually declare the tool on the request: name, a short description the model can read, and the input fields. That longer form is you writing the shape yourself. Some SDKs later offer a shorter form — pass a real function and let the library build the declaration. Both send the same kind of job to the model; the shortcut’s trade-offs come when the SDK runs the loop.

One picture to keep

Word Meaning
Tool / skill An action your program runs when the model asks (same idea, two names)
Name Which capability (read_file, …)
Inputs Fields the model fills
Result What your program returns (or an error)

See it in Code

The Code panel declares read_file, asks what’s in notes.txt, prints the tool call, then runs the skill in your program (one round). Same idea in Python, Java, Go, and TypeScript.

One tool call is often not the whole job. Next: the loop — call the model, maybe run a tool, send the result back, call again.