{
  "server": {
    "name": "liveagents-intelligence",
    "version": "1.0.0"
  },
  "count": 14,
  "tools": [
    {
      "name": "discover_intelligence",
      "needsKey": false,
      "description": "Find intelligence capabilities that can answer a question, ranked by what they have actually been shown to be good at in this exact context - the asset, the horizon, the market regime and the kind of question. Free, and it spends nothing: this is where to start. The ranking is returned with its own decomposition, so you can see why each source placed where it did, and some results are marked provisional, meaning they are being shown to earn a record rather than because they have one.",
      "arguments": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string",
            "description": "What the question is about, e.g. \"whale accumulation\" or \"shipping flows\"."
          },
          "asset": {
            "type": "string",
            "description": "Ticker, e.g. BTC. Omit for a question that is not about one instrument."
          },
          "query_type": {
            "type": "string",
            "description": "flow_change | level | anomaly_detection | directional | supply_pressure | demand_pressure | ranking | similarity | summary | lookup"
          },
          "horizon": {
            "type": "string",
            "description": "How far ahead the answer should be useful: 5m, 1h, 1-4h, 24h, 7d, 30d."
          },
          "regime": {
            "type": "string",
            "description": "The market regime you believe you are in: high_vol, low_vol, trending, sideways, risk_off."
          },
          "max_price": {
            "type": "string",
            "description": "The most you will pay per query, in LIVE."
          },
          "max_latency_ms": {
            "type": "number",
            "description": "Refuse sources slower than this."
          },
          "minimum_freshness": {
            "type": "number",
            "description": "Refuse sources whose data is older than this many seconds."
          },
          "min_reputation": {
            "type": "number",
            "description": "Refuse sources whose accuracy lower bound is under this, 0 to 1."
          },
          "limit": {
            "type": "number",
            "description": "How many to return. Default 5."
          }
        }
      }
    },
    {
      "name": "find_best_sources",
      "needsKey": false,
      "description": "The same search, but returning the trade-off rather than a winner. A question with four objectives - reputation, price, latency, freshness - usually has no single best answer, it has a frontier. Use this when you want to choose for yourself instead of accepting the default weighting, and it will tell you exactly what choosing each one costs you on the other axes.",
      "arguments": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "description": "Ticker."
          },
          "query_type": {
            "type": "string",
            "description": "The kind of question."
          },
          "horizon": {
            "type": "string",
            "description": "5m, 1h, 1-4h, 24h, 7d, 30d."
          },
          "regime": {
            "type": "string",
            "description": "The market regime."
          },
          "limit": {
            "type": "number",
            "description": "How many candidates to consider. Default 10."
          }
        }
      }
    },
    {
      "name": "describe_capability",
      "needsKey": false,
      "description": "Everything known about one capability: what it answers, how fresh it is, what it costs, how it is computed where that is knowable, and what its record looks like broken down by context. Read this before buying from a source you have not used.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "From discover_intelligence."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    },
    {
      "name": "get_source_reputation",
      "needsKey": false,
      "description": "What a source has actually been good at, as a vector rather than a score. Reputation here is per asset, per horizon, per regime and per question type, because a source can be excellent at four hours and worthless at a week - and one number for both is a number that is wrong twice. Includes the accuracy lower bound, the calibration, the sample size and how much of the record the provider reported about itself.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "From discover_intelligence."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    },
    {
      "name": "estimate_query_price",
      "needsKey": true,
      "description": "What one query would cost, and roughly what it would read, without committing to anything. Returns a quote id you can pass to query_intelligence; the quote holds the price for a couple of minutes and reserves nothing until you use it.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "From discover_intelligence."
          },
          "question": {
            "type": "string",
            "description": "The question, in plain words."
          },
          "asset": {
            "type": "string",
            "description": "Ticker."
          },
          "window_seconds": {
            "type": "number",
            "description": "How far back to look. Default 86400."
          },
          "horizon_seconds": {
            "type": "number",
            "description": "How far ahead the answer should be useful."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    },
    {
      "name": "query_intelligence",
      "needsKey": true,
      "description": "Buy and run one query. Reserves the LIVE, executes against the provider, validates the answer against the capability published schema, then settles - or refunds and tells you why. The reply is a structured envelope with the answer, the confidence, the freshness, the provenance and a hash you can keep. Record the response id when you act on it: report_decision is what turns this purchase into evidence, and evidence is what makes the next search better.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "From discover_intelligence."
          },
          "question": {
            "type": "string",
            "description": "The question, in plain words."
          },
          "asset": {
            "type": "string",
            "description": "Ticker."
          },
          "query_type": {
            "type": "string",
            "description": "Overrides what the question implies."
          },
          "window_seconds": {
            "type": "number",
            "description": "How far back to look. Default 86400."
          },
          "horizon_seconds": {
            "type": "number",
            "description": "How far ahead the answer should be useful."
          },
          "regime": {
            "type": "string",
            "description": "The market regime you believe you are in. Files the evidence correctly."
          },
          "quote_id": {
            "type": "string",
            "description": "From estimate_query_price. Omitted, one is taken at the published price."
          },
          "max_price": {
            "type": "string",
            "description": "Your ceiling, in LIVE. The query is refused rather than exceeding it."
          },
          "minimum_freshness": {
            "type": "number",
            "description": "Refuse and refund if the answer is older than this many seconds."
          },
          "idempotency_key": {
            "type": "string",
            "description": "Retry-safe. A repeated call with the same key charges once."
          },
          "nonce": {
            "type": "number",
            "description": "Strictly increasing per caller. Stops a captured request being replayed later."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    },
    {
      "name": "compare_intelligence",
      "needsKey": true,
      "description": "Ask several providers the same question and get the answers side by side, never averaged. Disagreement between high-reputation sources is itself intelligence and is more useful than a mean, which is a number nobody said. Costs the sum of the individual prices.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Two or more capability ids."
          },
          "question": {
            "type": "string",
            "description": "The question, asked of all of them."
          },
          "asset": {
            "type": "string",
            "description": "Ticker."
          },
          "window_seconds": {
            "type": "number",
            "description": "How far back to look."
          },
          "horizon_seconds": {
            "type": "number",
            "description": "How far ahead."
          },
          "regime": {
            "type": "string",
            "description": "The market regime."
          },
          "max_price_each": {
            "type": "string",
            "description": "Your ceiling per source, in LIVE."
          }
        },
        "required": [
          "capability_ids"
        ]
      }
    },
    {
      "name": "detect_intelligence_conflict",
      "needsKey": false,
      "description": "Given answers you already hold, measure how much the sources disagree and which camps they fall into, weighted by what each has been shown to be worth in this context. Use it to decide whether an apparent consensus is one, or one source repeated.",
      "arguments": {
        "type": "object",
        "properties": {
          "stances": {
            "type": "array",
            "description": "One entry per source: {capability_id, direction (-1,0,1), magnitude, confidence}.",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "stances"
        ]
      }
    },
    {
      "name": "get_evidence",
      "needsKey": false,
      "description": "What actually happened after this capability said things like this before. Returns the raw observations behind a reputation - how often the direction matched, over how many, and how they break down between the intelligence being wrong, the intelligence being read backwards, a fair call that did not come off, and an execution failure.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "From discover_intelligence."
          },
          "context_key": {
            "type": "string",
            "description": "Narrow it to one context."
          },
          "limit": {
            "type": "number",
            "description": "Default 50."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    },
    {
      "name": "get_provenance",
      "needsKey": false,
      "description": "How one specific response was produced: the capability version, the dataset version and its commitment where the data is hosted here, the retrieval method and its version, the model if one was involved, and the hash the provider signed. For a sovereign source this is honest about what is not knowable.",
      "arguments": {
        "type": "object",
        "properties": {
          "response_hash": {
            "type": "string",
            "description": "From the response envelope."
          }
        },
        "required": [
          "response_hash"
        ]
      }
    },
    {
      "name": "report_decision",
      "needsKey": true,
      "description": "Say what you decided and which responses informed it, with a weight for each. This is what turns a purchase into evidence, and it is the single most valuable call in this server: without it the network cannot learn which intelligence is worth anything. Include the responses you READ AND DID NOT USE in `ignored` - they are the control group, and leaving them out is the commonest way this data is made useless.",
      "arguments": {
        "type": "object",
        "properties": {
          "stance": {
            "type": "string",
            "description": "What you decided, in a word or two: LONG, SHORT, HOLD, REDUCE."
          },
          "asset": {
            "type": "string",
            "description": "Ticker."
          },
          "horizon_seconds": {
            "type": "number",
            "description": "How far ahead the decision looks."
          },
          "regime": {
            "type": "string",
            "description": "The market regime you believe you are in."
          },
          "rationale": {
            "type": "string",
            "description": "Why, briefly."
          },
          "used": {
            "type": "array",
            "description": "Responses that informed it: {response_id, weight}.",
            "items": {
              "type": "object"
            }
          },
          "ignored": {
            "type": "array",
            "description": "Response ids you read and did not act on.",
            "items": {
              "type": "string"
            }
          },
          "cohort": {
            "type": "string",
            "description": "An A/B label, if you are running one. The cleanest evidence there is."
          },
          "kind": {
            "type": "string",
            "description": "trade | allocation | risk | abstain. Default trade."
          }
        },
        "required": [
          "stance"
        ]
      }
    },
    {
      "name": "report_trade",
      "needsKey": true,
      "description": "Record what you actually did about a decision. Include the venue fill id in external_ref where you have one: an outcome that can be reconciled against the exchange is worth more than one taken on your word, and the network weights it accordingly.",
      "arguments": {
        "type": "object",
        "properties": {
          "decision_id": {
            "type": "string",
            "description": "From report_decision."
          },
          "venue": {
            "type": "string",
            "description": "Where it was executed."
          },
          "market": {
            "type": "string",
            "description": "The instrument."
          },
          "side": {
            "type": "string",
            "description": "buy or sell."
          },
          "qty": {
            "type": "number",
            "description": "Size."
          },
          "price": {
            "type": "number",
            "description": "Fill price."
          },
          "external_ref": {
            "type": "string",
            "description": "The venue own fill id."
          }
        },
        "required": [
          "decision_id"
        ]
      }
    },
    {
      "name": "report_outcome",
      "needsKey": true,
      "description": "What happened. Report losses as carefully as wins - a failed call is exactly as useful to this network as a successful one, and a record with only the wins in it is worthless. Set execution_ok false when the call was right and the fill was not: that keeps slippage off the provider record instead of charging them for your venue.",
      "arguments": {
        "type": "object",
        "properties": {
          "decision_id": {
            "type": "string",
            "description": "From report_decision."
          },
          "trade_id": {
            "type": "string",
            "description": "From report_trade, if there was one."
          },
          "realised_pct": {
            "type": "number",
            "description": "The realised return, in percent. Negative for a loss."
          },
          "horizon_seconds": {
            "type": "number",
            "description": "Over what period it was measured."
          },
          "regime_at_entry": {
            "type": "string",
            "description": "The regime when the position was opened."
          },
          "regime_at_exit": {
            "type": "string",
            "description": "And when it was closed."
          },
          "execution_ok": {
            "type": "boolean",
            "description": "False when the decision was right and the execution was not."
          },
          "notes": {
            "type": "string",
            "description": "Anything worth knowing."
          }
        },
        "required": [
          "decision_id",
          "realised_pct"
        ]
      }
    },
    {
      "name": "get_intelligence_roi",
      "needsKey": true,
      "description": "Whether buying a capability was followed by better decisions than comparable ones without it. Always returns an interval and a sample size, and says plainly when the difference is indistinguishable from zero. It is an association, never a demonstrated cause, and the answer says so.",
      "arguments": {
        "type": "object",
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "Which capability."
          },
          "days": {
            "type": "number",
            "description": "Window. Default 90."
          }
        },
        "required": [
          "capability_id"
        ]
      }
    }
  ]
}