Skip to main content

Documentation Index

Fetch the complete documentation index at: https://superwire.dev/llms.txt

Use this file to discover all available pages before exploring further.

Tool access is one of the most important differences between a demo agent and a backend AI feature. In a demo, it may be acceptable to give a model a broad toolbox and ask it to figure out what to use. In a product backend, that same pattern can be risky. Some tools may read sensitive data. Some may create records. Some may be expensive. Some may only make sense after another step has produced a required ID. Even read-only tools can create cost and latency problems if the model calls them unnecessarily. Superwire treats tool access as part of the workflow contract. The workflow can import MCP capabilities, but each agent only receives the capabilities it declares through uses. This creates a least-privilege model for AI steps.

​
Scoped capabilities

An agent does not need access to every tool just because the workflow knows those tools exist. A classification agent may only need the user request and lightweight metadata. A research agent may need a read-only fetch tool. A creation agent may need a write tool, but only after earlier steps have produced validated inputs. 
tool fetch_answer_detail from mcp.surveys.tool.fetch-answer-detail

agent select_answers {
    model: model.fast
    instruction: "Select the survey answers that are relevant to {{ input.question }}."

    output {
        answer_ids: [number]
    }
}

agent inspect_answers {
    model: model.smart
    uses: [tool.fetch_answer_detail]
    instruction: "Inspect only the selected answers: {{ agent.select_answers.answer_ids }}."

    output {
        findings: [string]
    }
}
The first agent has no tool access. It can decide which answer IDs matter based on lightweight context. The second agent receives a specific read tool because its job is to inspect selected details. That separation makes the workflow easier to reason about and safer to evolve.

​
Model-owned tool use

When a tool appears in an agent’s uses list, the model can decide whether and how to call it during that agent step. This is useful when the model needs judgment. For example, the model may inspect a set of search results and decide which records need more detail, or it may call a retrieval tool only when the prompt requires evidence. Model-owned tool use is powerful, but it should be scoped narrowly. The agent should only receive tools that are appropriate for its stage. The prompt should describe the purpose of the step, and the output schema should force the result into a shape the workflow can use later.

​
Workflow-owned tool calls

Some tool calls should not be left to model discretion. If the workflow always needs to fetch a task by ID, create a project before creating child tasks, or load a known resource before an agent runs, the workflow can call the tool directly. 
tool fetch_task from mcp.tasks.tool.fetch-task {
    bindings {
        workspace_id: input.workspace_id
    }
}

dynamic {
    task: call tool.fetch_task {
        bindings {
            task_id: input.task_id
        }
    }
}

agent summarize_task {
    model: model.fast
    instruction: "Summarize this task for a project manager: {{ task }}."

    output {
        summary: string
        risk_level: enum { low, medium, high }
    }
}
In this design, the model does not decide whether the task is fetched. The workflow does. The model receives the result and performs the reasoning step. This is the right boundary when the application requires a fixed operation.

​
Staged capability unlocking

Many backend operations have a natural order. A project must exist before tasks can be attached to it. A task group must exist before questions can be assigned to the group. A selected answer list should exist before transcript details are loaded. A reviewer step should run before a write tool receives the final payload. Superwire lets the workflow author express that order directly. Earlier steps produce IDs or structured decisions. Later steps can reference those values and receive additional capabilities only when they are relevant. This staged model avoids giving the model too much power too early. It also mirrors how backend domains usually work. Capabilities are unlocked by earlier results, not exposed all at once.

​
What this gives reviewers

Controlled tool access makes the workflow auditable. A reviewer can open the .wire file and answer practical questions: which model step can read user data, which step can create records, which tool calls are deterministic, and which tool calls are left to model judgment. That does not replace application-level authorization, rate limits, transactions, or human review where needed. It does make the AI orchestration layer much easier to inspect.