Skip to main content
You do not call the tools yourself. You ask Claude in plain words, and Claude picks the tool. This page lists the requests that map cleanly onto what the server offers, grouped by what you are trying to get done. The tool reference has every argument. Claude finds the project from the directory you started it in. Run it inside a repository Fermata already knows and “my pieces” means that project’s pieces. Anywhere else, name the project, or ask Claude to register the directory first.

See what needs you

get_piece is the one Claude reaches for before it acts. It returns the agent graph, the linked sessions, and legalActions: exactly what the piece accepts right now. An action outside that list fails and names the ones that would work, so Claude never has to guess.

Start work

Drafts

A draft is a card in the Backlog that waits until you release it. Filing one does not start anything, with one exception: a Loop-lane draft filed while that project’s Loop is playing starts at once, because Play is that lane’s standing release. Releasing keeps the draft’s id, so a piece Claude filed is the same id once it runs.

From an issue

create_draft takes issue: a Linear key like SUP-12, or a GitHub key like owner/repo#12. Fermata fetches the issue through the Stream Source linked to the project, files it as a draft whose spec is the issue, and formats it into a full spec when the draft is released. The branch carries the key and the pull request closes the issue, exactly as when you start from an issue in the app. An issue still blocked by open ones is filed anyway, and the result names the blockers so Claude can tell you. This needs Loop intake, another Edge feature, and a connected Stream Source. Without them the call fails with a sentence saying which is missing. When you wrote the spec yourself, pass the tickets as keys instead. Fermata checks every key against the tracker before it files anything, and one key it cannot verify fails the whole call (“Couldn’t verify SUP-12: ” and the reason). That check exists because a wrong key would put a closing line for an unrelated ticket in your pull request.

Move a piece along

Every step below is one piece_action call. Each one is legal only in the phase where the app would offer the same button.

Change the lane

“Put upload-retry on the Loop lane” is setLane. It is legal from the Spec step through planning, before agents run, and not while an interview turn or a plan build is in progress. Moving to Loop hands the piece to the Loop, which runs it while the project’s Loop is playing. See lanes. approveSpec takes only Manual and Auto, and refuses Loop. To put a piece on the Loop lane, use setLane.

Ask for changes

“Request changes on upload-retry: disable the retry button while offline” is requestChanges with your text. It starts a feedback session in the piece’s worktree, for the whole piece. It is legal at Review and on a completed piece whose branch still exists.

Send failed work back

When the work review fails, “send the failed agents back, and tell them to keep the old API” is two steps. sendBackToAgents sends the agents the review named back, each with the review’s findings and your guidance (up to 2,000 characters) in its brief. The piece lands paused, so Claude calls resumeAgents next. To send only some of them back, name them; Claude reads the list from the work review first.

Steer a failed agent

When an agent fails during the run and you know the fix, Claude can tell it rather than retry it blind. Each agent in get_piece says which of these apply right now, and why not when one doesn’t.
  • “Retry agent 3, and tell it files is a comma-separated string” is retryFailedAgents with that agent and your guidance (up to 2,000 characters). An agent whose session can be steered gets the note as its continue message; one that starts fresh gets it in its brief.
  • “Agent 3’s brief is wrong, it should read the config from .env” is editTaskBrief, while the run is paused or stopped. Nothing starts until Claude calls retryFailedAgents, which starts the agent fresh on the new brief. The agent’s card shows the brief changed over MCP.
  • “Tell agent 3 to use the existing helper” is messageTask, while the agent’s session is idle or failed. It is the same as typing into the session in Fermata: a failed agent runs again with the turn.
  • “Answer agent 3’s question: use Postgres” is answerTaskQuestion. Tool approvals and plan approvals stay yours, and are refused.
Messages and answers from Claude show in the transcript and the activity as sent over MCP. With Ask before runs and pull requests on, each of these waits for a card first. When the review failed only one agent’s work, “resume agent 7 and tell it to commit” is resumeTask. It sends that agent’s own session the review’s findings and your guidance, and leaves every other agent and the run as they are. If the old session can’t be resumed, a fresh one starts with the agent’s brief and the findings, and Fermata tells you so. Once the agent commits, the work review runs again. Only one resume runs on a piece at a time. With Ask before runs and pull requests on, it waits for a card first.

Finish

Merging is not on the list. Fermata opens the pull request and stops there; you merge.

Work on it yourself

“Open the upload-retry piece here, I want to fix something by hand” is open_piece_workspace. Fermata gets the piece’s worktree ready, recreating it from the branch if it was removed, and returns the path, the branch, the spec, and the strategy. It does not move your session: Claude asks you before it changes directory.