Sculptured docs

Agent tools

The tools Sculptured gives every Claude Code and Codex agent, what each one does, and what you see when an agent uses it.

Every agent Sculptured starts gets a small set of extra tools, next to the CLI's own. Agents use them to ask you questions, report findings, work with teammates and move work through a workflow. You do not call these tools yourself. This page explains what each one does, so you can write Jobs that use them and read what you see on the agent's page.

How agents get the tools

When the runner starts Claude Code or Codex, it adds one MCP server named rig. The CLI starts sculptured seat-tools for it, and each call travels over a private connection to the runner and then to your Sculptured.

sequenceDiagram
  participant A as Agent (Claude Code / Codex)
  participant T as rig tools (seat-tools)
  participant R as Runner on your computer
  participant S as Sculptured
  participant P as You
  A->>T: request_input {question}
  T->>R: the call, over a private socket
  R->>S: the call, over the computer's link
  S->>P: a question in Needs you
  P->>S: your answer
  S->>R: the answer
  R->>T: the answer
  T->>A: {text, question_id, timed_out}

In Claude Code the tools appear as mcp__rig__request_input and so on; in Codex as rig tools.

If the computer's connection drops while a call is waiting, the runner keeps the call and sends it again when the computer reconnects. Sculptured answers each call once, so a resent question is not asked twice. See When a computer goes offline.

Summary

ToolWho may call itWhat it does
request_inputany agentAsks you a question and waits for the answer.
record_decisionany agentSays what it decided after a question timed out.
reportany agentReports findings about the work it was handed.
approverestricted Claude Code agents onlyAsks you whether a tool may run.
spawn_agentany agentCreates a managed child agent.
send_agent_messageany agentMessages another agent in the project.
team_statusany agentReads the project's agents and their state.
dispatch_workthe workflow's dispatcher onlyCreates the batch of work items for a workflow.
complete_workthe agent holding an assignmentFinishes a workflow assignment with an outcome.
workflow_statusany agentReads the workflow's batch, assignments and reviews.
read_decisionsany agentReads the team's decision log.
search_historyany agentSearches what the team's agents already wrote, ran and were told.
record_lessonany agentRecords a lesson every agent of the team is told.
propose_changeany agentProposes a change to a business system and waits until it is approved or not.
write_statusthe status page's ownerReplaces the team's status page.
read_pdfany agentReads a PDF's text, page by page.
read_skillCodex agents with skillsLoads one of the agent's skills.

The three workflow tools are offered only to teams that have a workflow.

Questions and reports

request_input

Asks the person running the team a question and waits for the answer. The question appears in Needs you and on the agent. While it waits, the agent shows as waiting for input.

ParameterTypeRequiredMeaning
questionstringyesThe question.
optionslist of strings, or {label, description} objectsnoChoices to offer. You can always type another answer.
headerstringnoA short label shown above the question.
urgencylow, normal or highnoHow much the question holds up the work, in the agent's own words: high when it cannot go on or others wait on the answer, low for a preference it could decide itself. Urgent questions come first in Needs you and are marked Urgent, says the agent; low ones come last.

The agent receives { text, question_id, timed_out }.

You can answer while the agent's computer is offline. The answer reaches the agent when the computer reconnects.

record_decision

After a question timed out, the agent says what it decided and why. The decision is recorded on the question, so you can see what the agent chose in your absence.

ParameterTypeRequiredMeaning
question_idstringyesOne of this agent's own questions.
choicestringyesWhat it decided.
rationalestringnoWhy.

report

Reports findings about the work the agent was handed, for example the problems a review or a check found. It is shown to you labelled as reported by the agent. A report is the agent's claim, not a verified result.

ParameterTypeRequiredMeaning
summarystringyesThe short version.
findingslistnoEach item is a string, or {text, location} where location names a file or place.
verdictno-problems, problems-found or unsurenoThe agent's overall verdict.

approve

Claude Code's permission prompt, routed to you. It is given only to Claude Code agents whose permission is Restricted. When such an agent wants to run a tool that needs permission, you see "Allow tool to run?" with the tool's input, and choose Allow or Deny.

ParameterTypeRequiredMeaning
tool_namestringyesThe tool the agent wants to run.
inputobjectyesThe tool's input, shown to you.
tool_use_idstringnoClaude Code's id for the call.

Codex agents do not get approve. A restricted Codex agent asks through Codex's own approval requests, and Sculptured shows those to you as questions in the same way.

Working with teammates

spawn_agent

Creates a managed child agent. The child appears on the Run board under its parent, and it stops when its parent stops. It inherits its parent's model, folder and permissions.

ParameterTypeRequiredMeaning
request_idstringyesReuse the same id when retrying, so a retry does not create a second child.
namestringyesThe child's name on the board.
taskstringyesThe child's job, sent as its first message.

There are no fixed limits on children. A team can set its own (Most agents, children included and Most levels of children), and a refusal names the setting. A token limit set to include subagents counts the children's tokens toward the parent's limit. See Limits.

Use it for bounded, independent help. It does not replace the teammates you designed on the board.

send_agent_message

Sends a message to another agent in the project. If the recipient is busy, the message is queued; it does not interrupt the recipient's turn. You can read these messages in the team's communications.

ParameterTypeRequiredMeaning
request_idstringyesReuse the same id when retrying.
tostringyesThe recipient's exact id, from team_status.
textstringyesThe message. Agents are told to include context, the artifact's revision, the response they want and their own id.

team_status

Reads the project's current agents: their parent relationships, activity, lifecycle and stop controls. It takes no parameters. An open, idle session is reported as idle; it is not active work.

Workflows

These tools run a team that has a workflow: a dispatcher splits the work into items, and each item moves through stages.

dispatch_work

Only the workflow's dispatcher may call it. It creates one batch of work items for this run. A workflow with a dispatch command refuses it: the command's output, in this same shape, is the batch. It does not create agents; the stages' agents take the items.

ParameterTypeRequiredMeaning
batch_idstringyesThe batch's id. Repeating the identical batch is safe and does nothing.
summarystringyesShared goals, source map, and file and interface contracts.
taskslistyes1 to the workflow's task limit (at most 64).

Each task has:

FieldTypeRequiredMeaning
idstringyesThe item's id.
titlestringyesIts title.
contextstringyesSelf-contained sources, prerequisites, goals, where to put results and constraints.
modeindependent or dependentnoIndependent items may run at the same time.
depends_onlist of task idsnoItems that must be accepted before this one starts. Cycles are refused.

A team makes one batch per start. A different batch is refused until the team is stopped and started again.

complete_work

Finishes the agent's current workflow assignment with one of the stage's outcomes. The outcome chooses what happens next: the next stage, another review round, or completion. blocked is always available when the agent cannot safely continue.

ParameterTypeRequiredMeaning
assignmentstringyesThe assignment being finished.
outcomestringyesOne of the stage's outcomes, or blocked.
resultstringyesArtifact paths, the exact revision, sources, the checks actually run, and findings. At most 12,000 bytes.

The result stays agent-reported. A check stage, or a person's decision, is what independently confirms the work.

workflow_status

Reads the current batch, each item's context, the assignments and the review history. No parameters.

read_decisions

Reads the team's decision log: precedents people recorded, newest first, up to 50. Agents are told to check it before deciding something it may cover. It is read-only; agents cannot add to it. When the team's decision log is off, the agent is told so.

ParameterTypeRequiredMeaning
querystringnoWords to look for. Leave it out to read the latest entries.

What the team knows

These tools make no model calls. See What agents know.

search_history

Searches what this team's agents, including finished ones, wrote, ran, got back and were told, newest first. Each match gives the agent, the time, what kind of thing it was and the text around the match. It returns at most 8 matches and leaves out the asking agent's current turn. Agents use it before building something that may already exist, or to find which teammate knows about something.

ParameterTypeRequiredMeaning
querystringyesWords to find, at least 3 characters.
agentstringnoOnly this agent's history, by name or id.

record_lesson

Records a lesson for the team: something that cost the agent a wrong turn, in a sentence or two. Teammates already working get it with their next message, and every later agent in its briefing. You see it in the Knowledge view, where you can confirm or hide it.

ParameterTypeRequiredMeaning
lessonstringyesThe lesson. At most 400 characters are kept.
kindlesson or constraintnoconstraint: a rule every agent must follow in this project; it comes first in briefings. Default lesson.

When you confirm a lesson or constraint, it is also kept with the project for later teams; see Lessons kept with the project.

Changes to business systems

propose_change

Proposes a change to a business system, such as an order, a schedule or a record in the ERP, and waits for the decision; see Changes to business systems. Sculptured checks the team's rules against payload itself, then approves the change or asks a person. The reply says whether it is approved, by whom, each rule's result, and the proposal's id. Nobody answering in time means not approved. Proposing changes nothing by itself.

ParameterTypeRequiredMeaning
actionstringyesThe kind of change, as a short name, such as create_purchase_order. At most 80 characters. Rules name it.
summarystringyesOne line a person can approve from. At most 300 characters are kept.
payloadobjectyesThe change's fields, as they would be written. Rules read them. At most 32 KB.
systemstringnoWhich system it changes, such as ERP.
reasonstringnoWhy this change.

The status page

write_status

Replaces the team's status page: the one page that says where the work stands and what changed, under Results → Status. Only the agent that owns the page may call it; its briefing says so, and any other agent is told who does. Each call replaces the whole page, and every earlier version is kept.

ParameterTypeRequiredMeaning
markdownstringyesThe whole page, in Markdown. At most 64 KB.
donebooleannotrue for the final version, once the team's work is finished. Default false.

Reading files

read_pdf

Reads a PDF's text page by page, on the agent's own computer. Text costs a small fraction of what page images do, and an image stays in the agent's context for every later step. Pages with no text, such as scans and drawings, are named, so the agent looks at only those as images. One call returns at most about 60,000 bytes of text and says where to continue.

ParameterTypeRequiredMeaning
pathstringyesThe PDF.
pagesstringnoA page or range, such as 5 or 10-20. All pages when left out.

read_skill

Loads one of the agent's skills in full. Only Codex agents with skills get it; Claude Code loads skills natively.

ParameterTypeRequiredMeaning
namestringyesThe skill's name, as listed in the agent's briefing.

Limits on every call

LimitValueWhat the agent is told
Size of one call1 MiB"This call is too large for Sculptured (the limit is 1 MiB). Send a shorter question or report."
Calls one agent may have waiting16"This agent already has too many Sculptured tool calls waiting. Wait for one to finish."
Calls waiting on one computer256"Sculptured is handling too many tool calls right now. Try again in a moment."
Time to send a call10 seconds"Sculptured did not receive the whole tool call in time."

A call with wrong arguments is refused and kept as evidence on the agent, so you can see what it tried.

Next steps