<tools>
  <tool name="agent_finish">
    <description>Mark a subagent's task as completed and optionally report results to parent agent.

IMPORTANT: This tool can ONLY be used by subagents (agents with a parent).
Root/main agents must use finish_scan instead.

This tool should be called when a subagent completes its assigned subtask to:
- Mark the subagent's task as completed
- Report findings back to the parent agent

Use this tool when:
- You are a subagent working on a specific subtask
- You have completed your assigned task
- You want to report your findings to the parent agent
- You are ready to terminate this subagent's execution</description>
    <details>This replaces the previous finish_scan tool and handles both sub-agent completion
  and main agent completion. When a sub-agent finishes, it can report its findings
  back to the parent agent for coordination.</details>
    <parameters>
      <parameter name="result_summary" type="string" required="true">
        <description>Summary of what the agent accomplished and discovered</description>
      </parameter>
      <parameter name="findings" type="string" required="false">
        <description>List of specific findings, vulnerabilities, or discoveries</description>
      </parameter>
      <parameter name="success" type="boolean" required="false">
        <description>Whether the agent's task completed successfully</description>
      </parameter>
      <parameter name="report_to_parent" type="boolean" required="false">
        <description>Whether to send results back to the parent agent</description>
      </parameter>
      <parameter name="final_recommendations" type="string" required="false">
        <description>Recommendations for next steps or follow-up actions</description>
      </parameter>
    </parameters>
    <returns type="Dict[str, Any]">
      <description>Response containing: - agent_completed: Whether the agent was marked as completed - parent_notified: Whether parent was notified (if applicable) - completion_summary: Summary of completion status</description>
    </returns>
    <examples>
  # Sub-agent completing subdomain enumeration task
  <function=agent_finish>
  <parameter=result_summary>Completed comprehensive subdomain enumeration for target.com.
              Discovered 47 subdomains including several interesting ones with admin/dev
              in the name. Found 3 subdomains with exposed services on non-standard
              ports.</parameter>
  <parameter=findings>["admin.target.com - exposed phpMyAdmin",
                "dev-api.target.com - unauth API endpoints",
                "staging.target.com - directory listing enabled",
                "mail.target.com - POP3/IMAP services"]</parameter>
  <parameter=success>true</parameter>
  <parameter=report_to_parent>true</parameter>
  <parameter=final_recommendations>["Prioritize testing admin.target.com for default creds",
                             "Enumerate dev-api.target.com API endpoints",
                             "Check staging.target.com for sensitive files"]</parameter>
  </function>
    </examples>
  </tool>
  <tool name="create_agent">
    <description>Create and spawn a new agent to handle a specific subtask.

Only create a new agent if no existing agent is handling the specific task.</description>
    <details>The new agent inherits the parent's conversation history and context up to the point
  of creation, then continues with its assigned subtask. This enables decomposition
  of complex penetration testing tasks into specialized sub-agents.

  The agent runs asynchronously and independently, allowing the parent to continue
  immediately while the new agent executes its task in the background.

  If you as a parent agent don't absolutely have anything to do while your subagents are running, you can use wait_for_message tool. The subagent will continue to run in the background, and update you when it's done.
  </details>
    <parameters>
      <parameter name="task" type="string" required="true">
        <description>The specific task/objective for the new agent to accomplish</description>
      </parameter>
      <parameter name="name" type="string" required="true">
        <description>Human-readable name for the agent (for tracking purposes)</description>
      </parameter>
      <parameter name="inherit_context" type="boolean" required="false">
        <description>Whether the new agent should inherit parent's conversation history and context</description>
      </parameter>
      <parameter name="skills" type="string" required="false">
        <description>Comma-separated list of skills to use for the agent (MAXIMUM 5 skills allowed). Most agents should have at least one skill in order to be useful. Agents should be highly specialized - use 1-3 related skills; up to 5 for complex contexts. {{DYNAMIC_SKILLS_DESCRIPTION}}</description>
      </parameter>
    </parameters>
    <returns type="Dict[str, Any]">
      <description>Response containing: - agent_id: Unique identifier for the created agent - success: Whether the agent was created successfully - message: Status message - agent_info: Details about the created agent</description>
    </returns>
    <examples>
  # After confirming no SQL testing agent exists, create agent for vulnerability validation
  <function=create_agent>
  <parameter=task>Validate and exploit the suspected SQL injection vulnerability found in
              the login form. Confirm exploitability and document proof of concept.</parameter>
  <parameter=name>SQLi Validator</parameter>
  <parameter=skills>sql_injection</parameter>
  </function>

  <function=create_agent>
  <parameter=task>Test authentication mechanisms, JWT implementation, and session management
              for security vulnerabilities and bypass techniques.</parameter>
  <parameter=name>Auth Specialist</parameter>
  <parameter=skills>authentication_jwt, business_logic</parameter>
  </function>

  # Example of single-skill specialization (most focused)
  <function=create_agent>
  <parameter=task>Perform comprehensive XSS testing including reflected, stored, and DOM-based
              variants across all identified input points.</parameter>
  <parameter=name>XSS Specialist</parameter>
  <parameter=skills>xss</parameter>
  </function>

  # Example of up to 5 related skills (borderline acceptable)
  <function=create_agent>
  <parameter=task>Test for server-side vulnerabilities including SSRF, XXE, and potential
              RCE vectors in file upload and XML processing endpoints.</parameter>
  <parameter=name>Server-Side Attack Specialist</parameter>
  <parameter=skills>ssrf, xxe, rce</parameter>
  </function>
    </examples>
  </tool>
  <tool name="send_message_to_agent">
    <description>Send a message to another agent in the graph for coordination and communication.</description>
    <details>This enables agents to communicate with each other during execution, but should be used only when essential:
  - Sharing discovered information or findings
  - Asking questions or requesting assistance
  - Providing instructions or coordination
  - Reporting status or results

Best practices:
- Avoid routine status updates; batch non-urgent information
- Prefer parent/child completion flows (agent_finish)
- Do not message when the context is already known</details>
    <parameters>
      <parameter name="target_agent_id" type="string" required="true">
        <description>ID of the agent to send the message to</description>
      </parameter>
      <parameter name="message" type="string" required="true">
        <description>The message content to send</description>
      </parameter>
      <parameter name="message_type" type="string" required="false">
        <description>Type of message being sent: - "query": Question requiring a response - "instruction": Command or directive for the target agent - "information": Informational message (findings, status, etc.)</description>
      </parameter>
      <parameter name="priority" type="string" required="false">
        <description>Priority level of the message</description>
      </parameter>
    </parameters>
    <returns type="Dict[str, Any]">
      <description>Response containing: - success: Whether the message was sent successfully - message_id: Unique identifier for the message - delivery_status: Status of message delivery</description>
    </returns>
    <examples>
  # Share discovered vulnerability information
  <function=send_message_to_agent>
  <parameter=target_agent_id>agent_abc123</parameter>
  <parameter=message>Found SQL injection vulnerability in /login.php parameter 'username'.
              Payload: admin' OR '1'='1' -- successfully bypassed authentication.
              You should focus your testing on the authenticated areas of the
              application.</parameter>
  <parameter=message_type>information</parameter>
  <parameter=priority>high</parameter>
  </function>

  # Request assistance from specialist agent
  <function=send_message_to_agent>
  <parameter=target_agent_id>agent_def456</parameter>
  <parameter=message>I've identified what appears to be a custom encryption implementation
              in the API responses. Can you analyze the cryptographic strength and look
              for potential weaknesses?</parameter>
  <parameter=message_type>query</parameter>
  <parameter=priority>normal</parameter>
  </function>
    </examples>
  </tool>
  <tool name="view_agent_graph">
    <description>View the current agent graph showing all agents, their relationships, and status.</description>
    <details>This provides a comprehensive overview of the multi-agent system including:
  - All agent nodes with their tasks, status, and metadata
  - Parent-child relationships between agents
  - Message communication patterns
  - Current execution state</details>
    <returns type="Dict[str, Any]">
      <description>Response containing: - graph_structure: Human-readable representation of the agent graph - summary: High-level statistics about the graph</description>
    </returns>
  </tool>
  <tool name="wait_for_message">
    <description>Pause the agent loop indefinitely until receiving a message from another agent.

This tool puts the agent into a waiting state where it remains idle until it receives any form of communication. The agent will automatically resume execution when a message arrives.

IMPORTANT: This tool causes the agent to stop all activity until a message is received. Use it when you need to:
- Wait for subagent completion reports
- Coordinate with other agents before proceeding
- Synchronize multi-agent workflows

NOTE: If you are waiting for an agent that is NOT your subagent, you first tell it to message you with updates before waiting for it. Otherwise, you will wait forever!
</description>
    <details>When this tool is called, the agent (you) enters a waiting state and will not continue execution until:
  - Another agent sends a message via send_message_to_agent
  - Any other form of inter-agent communication occurs
  - Waiting timeout is reached

  The agent will automatically resume from where it left off once a message is received.
  This is particularly useful for parent agents waiting for subagent results or for coordination points in multi-agent workflows.
  NOTE: If you finished your task, and you do NOT have any child agents running, you should NEVER use this tool, and just call finish tool instead.
  </details>
    <parameters>
      <parameter name="reason" type="string" required="false">
        <description>Explanation for why the agent is waiting (for logging and monitoring purposes)</description>
      </parameter>
    </parameters>
    <returns type="Dict[str, Any]">
      <description>Response containing: - success: Whether the agent successfully entered waiting state - status: Current agent status ("waiting") - reason: The reason for waiting - agent_info: Details about the waiting agent - resume_conditions: List of conditions that will resume the agent</description>
    </returns>
    <examples>
  # Wait for subagents to complete their tasks
  <function=wait_for_message>
  <parameter=reason>Waiting for subdomain enumeration and port scanning subagents to complete their tasks and report findings</parameter>
  </function>

  # Coordinate with other agents
  <function=wait_for_message>
  <parameter=reason>Waiting for vulnerability assessment agent to share discovered attack vectors before proceeding with exploitation phase</parameter>
  </function>
    </examples>
  </tool>
</tools>
