{"service":"HALOWERK agentenwerk","endpoint":"/v1/intent-clarify","method":"POST","content_type":"application/json","inputSchema":{"type":"object","required":["candidates"],"additionalProperties":false,"properties":{"candidates":{"type":"array","minItems":2,"maxItems":50,"description":"The competing intents, two to fifty.","items":{"type":"object","required":["id","attributes"],"additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Identifier, unique within the call."},"label":{"type":"string","maxLength":300,"description":"Optional human-readable name, echoed unchanged."},"attributes":{"type":"object","description":"What distinguishes this candidate. Values must be scalar.","additionalProperties":{"type":["string","number","boolean","null"]}},"prior":{"type":"number","minimum":0,"maximum":1000,"default":1,"description":"Relative likelihood of this candidate before asking. Used to weight the expected outcome."}}}},"known":{"type":"object","description":"Attribute values already established, for example from earlier answers.","additionalProperties":{"type":["string","number","boolean","null"]}},"ask_about":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":128},"description":"Restrict the question to these attributes. Empty or absent means all of them."},"max_options":{"type":"integer","minimum":2,"maximum":10,"default":5,"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}}}},"requestExample":{"candidates":[{"id":"book_flight","label":"Book a flight","attributes":{"object":"travel","action":"book","urgency":"high"},"prior":3},{"id":"book_hotel","label":"Book a hotel room","attributes":{"object":"lodging","action":"book","urgency":"high"},"prior":2},{"id":"cancel_flight","label":"Cancel a flight","attributes":{"object":"travel","action":"cancel","urgency":"high"},"prior":1},{"id":"flight_status","label":"Check flight status","attributes":{"object":"travel","action":"inspect","urgency":"low"},"prior":4}],"known":{"urgency":"high"},"max_options":5,"attribute_prompts":{"action":"What would you like to do?"}},"operations":[{"method":"POST","inputSchema":{"type":"object","required":["candidates"],"additionalProperties":false,"properties":{"candidates":{"type":"array","minItems":2,"maxItems":50,"description":"The competing intents, two to fifty.","items":{"type":"object","required":["id","attributes"],"additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Identifier, unique within the call."},"label":{"type":"string","maxLength":300,"description":"Optional human-readable name, echoed unchanged."},"attributes":{"type":"object","description":"What distinguishes this candidate. Values must be scalar.","additionalProperties":{"type":["string","number","boolean","null"]}},"prior":{"type":"number","minimum":0,"maximum":1000,"default":1,"description":"Relative likelihood of this candidate before asking. Used to weight the expected outcome."}}}},"known":{"type":"object","description":"Attribute values already established, for example from earlier answers.","additionalProperties":{"type":["string","number","boolean","null"]}},"ask_about":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":128},"description":"Restrict the question to these attributes. Empty or absent means all of them."},"max_options":{"type":"integer","minimum":2,"maximum":10,"default":5,"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}}}},"requestExample":{"candidates":[{"id":"book_flight","label":"Book a flight","attributes":{"object":"travel","action":"book","urgency":"high"},"prior":3},{"id":"book_hotel","label":"Book a hotel room","attributes":{"object":"lodging","action":"book","urgency":"high"},"prior":2},{"id":"cancel_flight","label":"Cancel a flight","attributes":{"object":"travel","action":"cancel","urgency":"high"},"prior":1},{"id":"flight_status","label":"Check flight status","attributes":{"object":"travel","action":"inspect","urgency":"low"},"prior":4}],"known":{"urgency":"high"},"max_options":5,"attribute_prompts":{"action":"What would you like to do?"}}}],"example_request":{"candidates":[{"id":"book_flight","label":"Book a flight","attributes":{"object":"travel","action":"book","urgency":"high"},"prior":3},{"id":"book_hotel","label":"Book a hotel room","attributes":{"object":"lodging","action":"book","urgency":"high"},"prior":2},{"id":"cancel_flight","label":"Cancel a flight","attributes":{"object":"travel","action":"cancel","urgency":"high"},"prior":1},{"id":"flight_status","label":"Check flight status","attributes":{"object":"travel","action":"inspect","urgency":"low"},"prior":4}],"known":{"urgency":"high"},"max_options":5,"attribute_prompts":{"action":"What would you like to do?"}},"serviceName":"intent_clarify","tags":["agent","intent","disambiguation","dialogue"],"outputSchema":{"type":"object"},"outputExample":{"resolved":false,"remaining_candidates":["book_flight","book_hotel","cancel_flight"],"ruled_out":[{"id":"flight_status","label":"Check flight status","contradicts":{"attribute":"urgency","known_value":"high","candidate_value":"low"}}],"question":{"attribute":"object","prompt":"Which object applies?","prompt_source":"template","options":[{"value":"travel","keeps":["book_flight","cancel_flight"],"count":2,"prior_mass":4},{"value":"lodging","keeps":["book_hotel"],"count":1,"prior_mass":2}],"options_truncated":false,"expected_remaining_candidates":1.6667,"worst_case_remaining":2,"information_bits":0.848,"splits_cleanly":true},"alternatives":[{"attribute":"action","expected_remaining_candidates":1.8333,"worst_case_remaining":2,"information_bits":0.7105,"option_count":2,"splits_cleanly":true}],"unusable_attributes":[],"estimated_questions_remaining":2,"estimate_method":"Greedy worst case: take the best-ranked attribute, follow the branch with the most candidates, repeat. An upper bound for this strategy, not a proven minimum.","ranking_criteria":["expected_remaining_candidates asc","worst_case_remaining asc","option_count asc","attribute name asc"],"counts":{"candidates_in":4,"ruled_out":1,"remaining":3,"known_attributes_used":["urgency"]},"limits":"No language model and no natural-language understanding. Candidates, attributes and values are taken exactly as given and none are ever invented. A candidate that does not declare a known attribute is kept, because silence is not a contradiction; such candidates survive every branch of a question and are named under survive_every_answer. The question wording is a fixed template over the attribute name unless attribute_prompts supplies one. estimated_questions_remaining is a greedy worst-case upper bound, not a proven minimum. Stateless: no dialogue is remembered, so pass the accumulated answers back in known on the next call."}}