Make tools easy for agents to use

An agent picks a tool by reading its name and description, and then lives with whatever the tool returns. sokie init gives you a working first draft from the spec. These are the edits that turn it into tools agents use well. Run sokie dev while you work: each save reloads the server, and the warnings update.

To see what a live server serves, open its Tools tab in the app: every tool with its effect, its warnings and today's calls. A tool's page shows its entry as agents get it in tools/list, its input from the spec, and its week of calls. When the server is linked to its repository, the page also edits the tool: change its description, title, tags, effect, idempotent or response shape, review the file's diff, and Sokie opens a pull request with it. A warning the form can fix, such as an understated effect, has an Apply button that makes the change for you to review. On the Tools tab, Expose opens a pull request adding the tool file for a spec operation that has none.

To try a tool for real, open the Test tab: pick production or a live preview, fill in the tool's arguments, and call it as yourself. The call goes through the same runtime as any client, so it's metered and shows in Logs as "Sokie test". Anything that writes, deletes or acts on the world asks first. From a checkout, sokie call <tool> --input '<json>' does the same against sokie dev, or a deploy with --preview <n> or --production.

Write descriptions agents can choose from

A tool's description is the body of its file in tools/. Say what the tool returns and when to use it over its neighbours, in at least ten words:

---
operation: GET /tasks/{taskId}
title: Get a task
risk: read
---

Get one task by its id, with its title, status, due date and project. Use
`listTasks` to find an id first.

Spec summaries are often too short ("Find pet by ID") or only repeat the name. sokie check flags both, as description-thin and description-restates-name. Mention a related tool by name when the agent should call it first.

Set each tool's risk

risk tells clients what a call can do: read, write, delete or external_effect, for a tool that acts outside the API, like sending an email. Clients use it to decide when to ask before calling.

Until you set it, a tool takes its method's floor: GET is read, POST, PUT and PATCH are write, and DELETE is delete. A label can raise a tool above its floor but never lower it, so a POST that only searches stays at write. When a tool's name says delete or send but its risk is lower, sokie check flags it as effect-understated.

idempotent: true tells clients a tool is safe to retry.

Keep responses small

A list endpoint can return far more than an agent needs, and every byte fills its context. If the API takes a limit or page parameter, keep it on the tool. Otherwise, add project: with a JMESPath expression to keep only the fields that matter:

---
operation: GET /tasks
title: List tasks
risk: read
project: "[].{id: id, title: title, status: status, due: due}"
---

sokie check flags a list with neither as list-unbounded.

Leave out what agents shouldn't call

A tool exists because its file does. Delete a file in tools/ and that operation is no longer a tool. To keep an operation out at the source, mark it x-mcp: false in the spec. sokie check lists the spec's operations that have no tool, as a note, so nothing is left out by accident.

Many operations

With more than 40 operations, sokie init sets "discovery": "search". The server then offers three tools: one to search the others, one to read a tool's definition, and one to call it. Agents find what they need without the whole list in their context. A search for a tool's exact name or title puts that tool first, then tools whose names start with it. "discovery": "all" lists every tool.

Checks lists everything sokie check looks for.