# Halowerk Intent Clarifier

> Halowerk Intent Clarifier is a paid API for AI agents from agent.halowerk.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-13).

Given a list of candidate intents with distinguishing attributes and already-known values, returns the single most informative question to ask next to narrow down which intent the user has.

## Facts

- Endpoint: POST https://agent.halowerk.com/v1/intent-clarify
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/halowerk-intent-clarifier-64f80c93
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_233rsYrMWRhTpZvggrP_j

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability halowerk-intent-clarifier-64f80c93 -d '<json body>'
```

Example prompt: I have four candidate intents — 'book_flight', 'check_flight_status', 'cancel_flight', and 'upgrade_seat' — each with attributes like destination, date, and booking_ref. I already know the user's destination is 'London'. Which single attribute should I ask about next to best narrow down which intent they have?

## When to prefer this

Choose this endpoint when you have a well-defined set of competing intents (2–50) each described by explicit attributes, and you want an optimal next clarifying question rather than generating questions heuristically. It is especially useful in multi-turn conversational flows where you accumulate answers incrementally and need to minimize the number of questions asked. Prefer it over general LLM prompting when you need deterministic, weighted candidate elimination with explicit ruled-out reasoning.

## Known failure modes

- Fewer than 2 candidates provided — validation error
- Candidate attributes contain non-scalar values — schema rejection
- max_options outside 2–10 range — validation error
- ask_about references attributes not present in any candidate — may return no useful question
- All candidates share the same value for every attribute — no discriminating question can be found
- Candidates list exceeds 50 items — rejected
- Attribute prompt string exceeds 300 characters — truncation or rejection

## How this service works

Takes a list of candidate intents, each described by attributes, plus whatever is already known, and returns the one attribute worth asking about next. Candidates contradicted by the known values are ruled out first and listed with the attribute that excluded them; a candidate that simply does not declare a known attribute is kept, because silence is not a contradiction.

## Output

Returns the single attribute whose answer would most effectively narrow down the list of candidate intents, along with a suggested question (using custom wording if provided), the set of allowable answer options, any values omitted due to the max_options cap, and a list of candidates already ruled out with the attribute that excluded each one.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "known": {
   "type": "object",
   "description": "Attribute values already established, for example from earlier answers.",
   "additionalProperties": {
    "type": [
     "string",
     "number",
     "boolean",
     "null"
    ]
   }
  },
  "ask_about": {
   "type": "array",
   "items": {
    "type": "string",
    "maxLength": 128,
    "minLength": 1
   },
   "maxItems": 50,
   "description": "Restrict the question to these attributes. Empty or absent means all of them."
  },
  "candidates": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "id",
     "attributes"
    ],
    "properties": {
     "id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 1,
      "description": "Identifier, unique within the call."
     },
     "label": {
      "type": "string",
      "maxLength": 300,
      "description": "Optional human-readable name, echoed unchanged."
     },
     "prior": {
      "type": "number",
      "default": 1,
      "maximum": 1000,
      "minimum": 0,
      "description": "Relative likelihood of this candidate before asking. Used to weight the expected outcome."
     },
     "attributes": {
      "type": "object",
      "description": "What distinguishes this candidate. Values must be scalar.",
      "additionalProperties": {
       "type": [
        "string",
        "number",
        "boolean",
        "null"
       ]
      }
     }
    },
    "additionalProperties": false
   },
   "maxItems": 50,
   "minItems": 2,
   "description": "The competing intents, two to fifty."
  },
  "max_options": {
   "type": "integer",
   "default": 5,
   "maximum": 10,
   "minimum": 2,
   "description": "How many answer options the question may offer. Excess values are named under omitted_values, never dropped silently."
  },
  "attribute_prompts": {
   "type": "object",
   "description": "Your own question wording per attribute. Used verbatim where given.",
   "additionalProperties": {
    "type": "string",
    "maxLength": 300
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/halowerk-intent-clarifier-64f80c93/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent.halowerk.com](https://www.zero.xyz/host/agent.halowerk.com/llms.txt)