Agent-as-Tool

Any agent can become a callable tool for other agents. A parent agent dispatches work to specialist sub-agents, each running its own model, tools, and context strategy.

How Agent-Tools Work

An agent becomes a tool when its agent_type is set to "tool". This changes the agent from something you invoke directly to something other agents (or you) invoke programmatically with structured inputs and outputs.

The core difference: a regular agent receives free-form messages. An agent-tool receives typed parameters and returns typed output.

Define the Input Schema

The input schema declares what parameters the agent-tool accepts. Each parameter has 4 properties:

Property	Type	Purpose
name	string	Parameter identifier passed to the agent
type	string | number | boolean	Data type for validation
description	string	Explains what this parameter controls — included in the tool definition sent to the parent agent
required	boolean	Whether the parent agent must provide this parameter

Example input schema for a “Research Agent” tool:

{
  "parameters": [
    {
      "name": "topic",
      "type": "string",
      "description": "The subject to research — be specific about scope and depth expected",
      "required": true
    },
    {
      "name": "max_sources",
      "type": "number",
      "description": "Maximum number of sources to consult before synthesizing findings",
      "required": false
    },
    {
      "name": "include_citations",
      "type": "boolean",
      "description": "Whether to include source URLs in the output",
      "required": false
    }
  ]
}

Define the Output Schema

The output schema declares what the agent-tool returns. This shapes the structured data the parent agent receives.

{
  "output": [
    {
      "name": "summary",
      "type": "string",
      "description": "Synthesized findings in 2-4 paragraphs"
    },
    {
      "name": "source_count",
      "type": "number",
      "description": "Number of sources consulted"
    },
    {
      "name": "confidence",
      "type": "string",
      "description": "Self-assessed confidence level: high, medium, or low"
    }
  ]
}

The agent-tool’s system prompt should instruct it to produce output matching this schema. QARK validates the return structure and surfaces mismatches in the execution trace.

Control Recursion Depth

Agent-tools can call other agent-tools. A “Project Manager” dispatches a “Research Agent” which dispatches a “Web Search Agent.” This nesting is powerful — and needs a safety boundary.

Max recursion depth defaults to 3. This means:

• Depth 0: the root conversation
• Depth 1: the first agent-tool called
• Depth 2: a sub-agent called by the depth-1 agent
• Depth 3: maximum — calls beyond this depth are rejected

Set the recursion depth per agent-tool in the editor. Lower it to 1 for leaf-node agents that should never delegate. Raise it (with caution) for orchestration patterns that require deeper nesting.

Set Availability Mode

Each agent-tool has an availability mode that controls where it appears:

Mode	Behavior
agents_only	The tool is visible only to other agents. It does not appear in the @mention selector or manual tool picker. Use this for specialist sub-agents that should not be invoked directly.
everywhere	The tool appears in the @mention selector and is available to other agents. Use this for agent-tools that are useful both as standalone agents and as sub-agents.

Track Nested Execution

When an agent-tool runs, QARK creates an AgentToolActivity record with full execution visibility:

Field	Content
agentName	The name of the agent-tool being executed
depth	Current nesting level (1, 2, 3…)
content	The messages exchanged during the agent-tool’s execution
subToolCalls	Any tools (including other agent-tools) invoked during execution
status	running, completed, or error
finalOutput	The structured output returned to the parent agent

The execution trace renders in the conversation UI with depth indentation — each nesting level is visually offset so you can follow the chain from parent agent through sub-agents down to individual tool calls and back up to the final result.

Tool Turn Elevation

Standard conversations allocate a base number of tool turns per response cycle. When agent-tools are active, QARK elevates the tool turn limit to 50. This ensures that complex multi-agent workflows — where a parent agent dispatches several sub-agents, each making multiple tool calls — have sufficient headroom to complete without hitting artificial limits.

This elevation applies automatically when any agent-tool is present in the active tool set. No configuration needed.

Example: Orchestrator Pattern

A “Project Manager” agent demonstrates the full agent-as-tool flow:

Project Manager (root agent)

• Model: Claude Sonnet
• Tools: Research Agent (agent-tool), Writing Agent (agent-tool), file operations
• System prompt: “You coordinate research and writing tasks. Break complex requests into research and writing phases.”

Research Agent (agent-tool, agents_only)

• Model: Claude Sonnet
• Tools: web search, URL reader
• Input: topic (string, required), depth (string: “shallow” | “deep”, required)
• Output: findings (string), sources (number)
• Max recursion depth: 1

Writing Agent (agent-tool, agents_only)

• Model: Claude Sonnet
• Tools: file write, markdown formatter
• Input: content (string, required), format (string: “report” | “summary” | “email”, required)
• Output: document (string), word_count (number)
• Max recursion depth: 1

When you ask the Project Manager to “research quantum computing advances in 2025 and write a briefing document,” the execution trace shows:

1. Project Manager receives your request (depth 0)
2. Project Manager calls Research Agent with {topic: "quantum computing advances 2025", depth: "deep"} (depth 1)
3. Research Agent calls web search tool, reads 8 URLs, returns findings (depth 1 completes)
4. Project Manager calls Writing Agent with {content: <research findings>, format: "report"} (depth 1)
5. Writing Agent produces the document, returns it (depth 1 completes)
6. Project Manager delivers the final briefing to you (depth 0 completes)

Every step is visible. Every tool call is logged. Every token is counted.

Note that in step 4, the Project Manager does not paste the full research findings into the Writing Agent’s input. Instead, QARK automatically saves the Research Agent’s output to a file and gives the Project Manager a compact reference with a file path, word count, and preview. The Project Manager passes that file path to the Writing Agent, which reads it from disk. This keeps the Project Manager’s context window lean — see The File-as-Bus Pattern for details.