Raw schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Inline JSON rows (SYNCHRONOUS β the ranking returns immediately). Best for a few hundred rows: the data rides inside your tool-call payload, so your CLIENT's per-message budget (Claude Code ~25k tokens, Claude Desktop ~150k chars) usually binds well before the server ceiling (~4MB / 2000 rows / 64 columns). Each row is one entity observation. For anything medium or larger, use dataset_id / fetch_url / direct_upload."
},
"csv": {
"type": "string",
"description": "Inline CSV text β header row + data rows (SYNCHRONOUS). Same small-inline budget as rows; a convenience when you already hold CSV. For anything larger, use dataset_id / fetch_url / direct_upload."
},
"fetch_url": {
"type": "string",
"description": "Public https URL the SERVER fetches, parses, and ranks in ONE async call (collapses hs_provide_dataset + hs_rank_topk). Returns { status:\"pending\", task_id } β poll hs_poll_task. Internal/private/non-https URLs are refused."
},
"dataset_id": {
"type": "string",
"description": "A dataset already registered via hs_provide_dataset (upload or fetch), for larger data. ASYNC β returns { status:\"pending\", task_id }; poll hs_poll_task."
},
"direct_upload": {
"type": "boolean",
"const": true,
"description": "Set true to receive a direct-to-storage PUT URL (upload_url + dataset_id) for a large dataset (~1M rows), bypassing the inline/proxy caps. NO ranking starts: PUT your CSV, then call hs_rank_topk again with the returned dataset_id."
}
},
"additionalProperties": false,
"description": "Exactly one data source: rows or csv (small, inline, synchronous) | fetch_url or dataset_id (async, poll hs_poll_task) | direct_upload:true (get an upload URL β no run starts)."
},
"outcome_column": {
"type": "string",
"minLength": 1,
"description": "The column holding the yes/no result to learn to predict. Must be known historically - not derived after the outcome (that is leakage)."
},
"entity_column": {
"type": "string",
"minLength": 1,
"description": "What each row represents, e.g. customer_id, machine_id, application_id."
},
"subject_kind": {
"type": "string",
"enum": [
"person",
"org",
"object",
"event",
"other"
],
"description": "What kind of thing each entity is. \"person\" enables decision-support safeguards."
},
"horizon": {
"type": "string",
"description": "The time window the prediction is about, e.g. \"30 days\"."
},
"page": {
"type": "object",
"properties": {
"k": {
"type": "number",
"description": "How many top entities to return (default 20, max 100)."
},
"offset": {
"type": "number"
}
},
"additionalProperties": false
},
"acknowledge_decision_support": {
"type": "boolean",
"description": "Required true when subject_kind is \"person\" and the outcome is in a regulated domain (hiring, credit, education, insurance, benefits, justice). Confirms results are decision-support with human review."
},
"idempotency_key": {
"type": "string",
"maxLength": 120,
"description": "For dataset_id runs: reuse to dedupe retried submissions onto the same task."
}
},
"required": [
"data",
"outcome_column",
"entity_column",
"subject_kind"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}