---
title: "Get Tool Schemas"
method: GET
path: "/api/comms/tools/schemas"
tags: ["comms"]
---

# Get Tool Schemas

`GET /api/comms/tools/schemas`

## Request

- Base URL: `https://api.superit.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.superit.ai/api/comms/tools/schemas`
- Auth: HTTP bearer

Return typed schemas for all available Sparky tools.

## Response `200`

Successful Response

- ToolSchemasResponse: All available Sparky tool schemas.
  - `tool_names` SparkyToolName[], required
  - `tools` union[], required
    - union
      - RunCommandSchema
        - `tool` 'run_command'
        - `description` string
        - `requires_session` boolean
        - `input` RunCommandInput
          - `full_command` string, required
          - `reason` string, required
          - `risk` string, required
          - `elevated` 'system', nullable
          - `title` string, nullable
        - `output` CommandHandle: Durable handle for a device command. run_command and check_command both return this shape; ``output`` is set only once the command is terminal.
          - `handle` string, required: Durable command handle; pass to check_command to poll progress. The device-offline sentinel means no execution exists; do not poll.
          - `status` string, required: One of: queued, running, device_unreachable, waiting_for_approval, completed, failed, timeout, denied, offline. Offline means no command was started; reconnect before retrying.
          - `detail` string: Guidance about the current state.
          - `output` SrvMeshSparkyContractsCommandCommandOutput: Final result of a device command execution.
            - `id` string, required: Mesh command execution id when the agent ran the command; synthetic value `policy-blocked` when validation blocked before execution.
            - `stdout` string, required: Standard output from command
            - `stderr` string, required: Standard error from command
            - `exit_code` integer, required: Command exit code
            - `error` string: Execution error message if any
            - `output_note` string: Set when output was cut or shortened: what was lost, where, and how to read the rest.
            - `evidence_refs` CaptureRef[]
              - …
      - RunDeviceScriptSchema
        - `tool` 'run_device_script'
        - `description` string
        - `requires_session` boolean
        - `input` RunDeviceScriptInput
          - `article_slug` string, required
          - `resource_slug` string, required
          - `parameters` object, nullable
        - `output` SrvCommsRoutesToolsCommandOutput
          - `id` string, required
          - `stdout` string, required
          - `stderr` string, required
          - `exit_code` integer, required
          - `error` string
      - TakeScreenshotSchema
        - `tool` 'take_screenshot'
        - `description` string
        - `requires_session` boolean
        - `input` ScreenshotInput
          - `reason` string, required
      - GetComputerSchema
        - `tool` 'get_computer'
        - `description` string
        - `requires_session` boolean
      - SearchKbSchema
        - `tool` 'search_kb'
        - `description` string
        - `input` SearchKbInput
          - `query` string, nullable
      - GetKbArticleSchema
        - `tool` 'get_kb_article'
        - `description` string
        - `input` GetKbArticleInput
          - `slug` string, required
      - LoadSkillSchema
        - `tool` 'load_skill'
        - `description` string
        - `input` LoadSkillInput
          - `name` string, required
        - `output` LoadSkillOutput
          - `slug` string, required
          - `name` string, required
          - `description` string, required
          - `content` string, required
      - WebSearchSchema
        - `tool` 'web_search'
        - `description` string
        - `input` WebSearchInput
          - `query` string, required
          - `max_results` integer
      - TicketGetSchema
        - `tool` 'ticket_get'
        - `description` string
        - `input` TicketGetInput
          - `ticket_key` string, required
      - TicketPersistSchema
        - `tool` 'ticket_persist'
        - `description` string
        - `input` TicketPersistInput
          - `description` string, required
          - `ticket_key` string, nullable
          - `note` string, nullable
      - SearchFtsSchema
        - `tool` 'search_fts'
        - `description` string
        - `input` SearchFtsInput
          - `query` string, required
          - `domains` string[], nullable
          - `limit` integer
      - AnalyseDataSchema
        - `tool` 'analyse_data'
        - `description` string
        - `input` AnalyseDataInput
          - `question` string, required
          - `domains` string[], required
      - GetTicketAnalysisSchema
        - `tool` 'get_ticket_analysis'
        - `description` string
        - `input` GetTicketAnalysisInput
          - `ticket_key` string, required
      - InsightGetSchema
        - `tool` 'insight_get'
        - `description` string
        - `input` InsightGetInput
          - `insight_key` string, required
        - `output` InsightGetToolResult: Insight recommendation details for Sparky.
          - `key` string, required
          - `title` string, required
          - `description` string, required
          - `recommended_action` string, required
          - `insight_type` string, required
          - `category` string, required
          - `urgency` string, nullable
          - `priority` string, nullable
          - `confidence` string, nullable
          - `status` string, required
          - `source_ticket_count` integer, required
          - `source_ticket_keys` string[]
      - TwinMetricsSchema
        - `tool` 'twin_metrics'
        - `description` string
        - `input` TwinMetricsInput
          - `devices` string[], required
          - `metrics` string[], required
          - `range` '1h' | '6h' | '24h' | '3d' | '7d'
          - `start` string, date-time, nullable
          - `disk_path` string, nullable
        - `output` TwinMetricsResult
          - `start` string, date-time, required
          - `end` string, date-time, required
          - `granularity` '5m' | '1h', required
          - `devices` DeviceSeries[], required
            - `hostname` string, required
            - `device_key` string, required
            - `series` object, required
          - `unresolved` UnresolvedDevice[], required
            - `query` string, required
            - `reason` 'not_found' | 'ambiguous', required
            - `candidates` DeviceCandidate[], required
              - …
          - `evidence_refs` CaptureRef[]
            - `capture_key` string, required
            - `path` string
      - TwinChangesSchema
        - `tool` 'twin_changes'
        - `description` string
        - `input` TwinChangesInput
          - `devices` string[], required
          - `domains` string[], nullable
          - `range` '24h' | '7d' | '30d' | '90d'
          - `start` string, date-time, nullable
        - `output` TwinChangesResult
          - `start` string, date-time, required
          - `end` string, date-time, required
          - `devices` DeviceChanges[], required
            - `hostname` string, required
            - `device_key` string, required
            - `changes` DeviceChange[], required
              - …
          - `unresolved` UnresolvedDevice[], required
            - `query` string, required
            - `reason` 'not_found' | 'ambiguous', required
            - `candidates` DeviceCandidate[], required
              - …
          - `evidence_refs` CaptureRef[]
            - `capture_key` string, required
            - `path` string
      - ExploreSchema
        - `tool` 'explore'
        - `description` string
        - `input` ExploreInput
          - `objective` string, required
      - TodoAddSchema
        - `tool` 'todo_add'
        - `description` string
        - `input` TodoAddInput
          - `names` string[], required
        - `output` TodoToolResult
          - `items` TodoItem[], required
            - `name` string, required
            - `status` 'not_started' | 'started' | 'done' | 'skipped'
          - `summary` string, required
          - `changed` string, nullable
      - TodoStartSchema
        - `tool` 'todo_start'
        - `description` string
        - `input` TodoStartInput
          - `name` string, required
        - `output` TodoToolResult
          - `items` TodoItem[], required
            - `name` string, required
            - `status` 'not_started' | 'started' | 'done' | 'skipped'
          - `summary` string, required
          - `changed` string, nullable
      - TodoCompleteSchema
        - `tool` 'todo_complete'
        - `description` string
        - `input` TodoCompleteInput
          - `name` string, required
        - `output` TodoToolResult
          - `items` TodoItem[], required
            - `name` string, required
            - `status` 'not_started' | 'started' | 'done' | 'skipped'
          - `summary` string, required
          - `changed` string, nullable
      - TodoSkipSchema
        - `tool` 'todo_skip'
        - `description` string
        - `input` TodoSkipInput
          - `name` string, required
        - `output` TodoToolResult
          - `items` TodoItem[], required
            - `name` string, required
            - `status` 'not_started' | 'started' | 'done' | 'skipped'
          - `summary` string, required
          - `changed` string, nullable
      - ActionRunSchema
        - `tool` 'action_run'
        - `description` string
        - `input` ActionRunInput
          - `action_key` string, required
          - `inputs` object, nullable
      - ActionGetSchema
        - `tool` 'action_get'
        - `description` string
        - `input` ActionGetInput
          - `action_key` string, required
      - ActionGetRunSchema
        - `tool` 'action_get_run'
        - `description` string
        - `input` ActionGetRunInput
          - `run_key` string, required
      - ActionExecutionListSchema
        - `tool` 'action_execution_list'
        - `description` string
        - `input` ActionExecutionListInput
          - `statuses` string[], nullable
      - ActionListSchema
        - `tool` 'action_list'
        - `description` string
      - CommandApprovalGetSchema
        - `tool` 'command_approval_get'
        - `description` string
        - `input` CommandApprovalGetInput
          - `approval_key` string, required
      - ActionProposeDraftSchema
        - `tool` 'action_create'
        - `description` string
        - `input` ActionProposeDraftInput
          - `name` string, required
          - `description` string, required
      - ActionUpdateDraftSchema
        - `tool` 'action_update'
        - `description` string
        - `input` ActionUpdateDraftInput
          - `action_key` string, required
          - `changes` string, required
      - ShowVideoSchema
        - `tool` 'show_video'
        - `description` string
        - `input` ShowVideoInput
          - `youtube_id` string, required
          - `title` string, required
        - `output` VideoToolOutput
          - `kind` 'video'
          - `youtube_id` string, required
          - `title` string, required

## Other responses

- `400`: Invalid input
- `401`: Not authenticated
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Conflict

---

[API](https://skmtc.dev/superit/apis/super-it-api.md) - [All operations](https://skmtc.dev/superit/apis/super-it-api/llms.txt) - [OpenAPI document](https://skmtc.dev/superit/apis/super-it-api/revisions/4944d556c2bb?raw)