# Cue (`cue-1`): Tool calling (function selection)

Turn a request into the right function call with valid arguments.

Cue reads what someone asked for and picks which of your functions to call, then fills in its arguments. The arguments always validate against that function's JSON Schema, and when nothing fits you get `tool: null` instead of a forced guess.

Send tools in OpenAI, Anthropic or plain `{name, description, parameters}` format. It's built for voice commands, chat shortcuts and routing inside apps, where a frontier model is slow and expensive for a menu choice.

- **Price:** $0.30 per 1,000 calls. One unit per started 2,000 characters of input.
- **Languages:** ~30 languages

- **Input:** The user's request (string or array of up to 8).
- **Batch:** yes, up to 8 inputs per call
- **Status:** live
- **Built on:** [Qwen/Qwen3-0.6B (with JSON-schema constrained decoding)](https://huggingface.co/Qwen/Qwen3-0.6B), Apache-2.0, 0.6B

## Request

```bash
curl https://labs.greatwork.company/v1/run \
  -H "Authorization: Bearer $GWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"cue-1","input":"is it going to be cold in Chicago tomorrow? use fahrenheit","tools":[{"name":"get_weather","description":"Weather forecast for a city","parameters":{"type":"object","properties":{"city":{"type":"string"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["city"]}},{"name":"send_message","description":"Send a text message to a contact","parameters":{"type":"object","properties":{"to":{"type":"string"},"body":{"type":"string"}},"required":["to","body"]}}]}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string or string[] | yes | | The user's request (string or array of up to 8). |
| `tools` | object[] | yes |  | 1 to 32 functions: `{name, description, parameters}` (JSON Schema object). OpenAI `{type: "function", function: {...}}` and Anthropic `{name, input_schema}` shapes work too. |
| `tool_choice` | string (auto \| required) | no | `"auto"` | `required` always picks a function; `auto` can answer `tool: null` when none fits. |
| `instructions` | string | no |  | Extra guidance, e.g. "the user is in Chicago" or "prefer search_orders for anything about a purchase". |

## Output

| Field | Type | Description |
|---|---|---|
| `tool` | string | Name of the function to call, or null when none fits. |
| `arguments` | object | Arguments matching that function's schema (null when `tool` is null). |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`. With an array input, `output` is an array in the same order.

## Examples (real outputs from our servers)

### Weather

```json
{
  "model": "cue-1",
  "input": "is it going to be cold in Chicago tomorrow? use fahrenheit",
  "tools": [
    {
      "name": "get_weather",
      "description": "Weather forecast for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "enum": [
              "celsius",
              "fahrenheit"
            ]
          }
        },
        "required": [
          "city"
        ]
      }
    },
    {
      "name": "send_message",
      "description": "Send a text message to a contact",
      "parameters": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "to",
          "body"
        ]
      }
    }
  ]
}
```

```json
{
  "tool": "get_weather",
  "arguments": {
    "city": "Chicago",
    "unit": "fahrenheit"
  }
}
```

4884 ms, $0.0003.

### Text a contact

```json
{
  "model": "cue-1",
  "input": "text mom that I'll be 10 minutes late",
  "tools": [
    {
      "name": "get_weather",
      "description": "Weather forecast for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ]
      }
    },
    {
      "name": "send_message",
      "description": "Send a text message to a contact",
      "parameters": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "to",
          "body"
        ]
      }
    }
  ]
}
```

```json
{
  "tool": "send_message",
  "arguments": {
    "to": "mom",
    "body": "I'll be 10 minutes late"
  }
}
```

4664 ms, $0.0003.

### Nothing fits

```json
{
  "model": "cue-1",
  "input": "what's 17 times 23?",
  "tools": [
    {
      "name": "get_weather",
      "description": "Weather forecast for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ]
      }
    },
    {
      "name": "send_message",
      "description": "Send a text message to a contact",
      "parameters": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "to",
          "body"
        ]
      }
    }
  ]
}
```

```json
{
  "tool": null,
  "arguments": null
}
```

2533 ms, $0.0003.

## Good for

- Voice commands in apps ("text mom I'm late")
- Route chat messages to the right handler
- Fill forms from one sentence
- Cheap first pass before a big agent

## Limits and caveats

- Relative dates and times ("next Tuesday at 3pm") are often wrong: resolve them in your code, or pass today's context in `instructions`.
- Best with up to about 10 clearly different functions; similar names and descriptions get confused.
- One function per request; it doesn't plan multi-step work.
