fahali-mcp

fahali_get_capital_flow

Read-onlyIdempotent

Retrieve candle-derived 60-minute USD order-flow imbalance readings for specified symbols, or default readings when none are supplied, to gauge short-term capital-flow pressure.

Instructions

Measured 60-minute USD order-flow imbalance for requested symbols, or the strongest available readings when none are supplied. Zero detector score does not erase netFlowUsd: the score measures unusualness, not data presence. Candle-derived proxy only; no exchange aggressor tape, participant identity, fund-flow attribution, or forecast.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "fahali_get_capital_flow"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Source-side row depth.
`since`	No	ISO-8601 lower bound, no more than 7 days ago. Defaults to 96h ago; out-of-range values are rejected with invalid_since, never silently defaulted.
`detail`	No	Response depth. audit is the full-fidelity default; brief and standard are explicit compact projections.	audit
`symbol`	No	Optional single instrument. Base aliases such as BTC resolve transparently to a preferred quoted pair and the resolution is returned.
`symbols`	No	Optional comma-separated instruments (max 100). Applied in SQL at the source.
`include_withheld`	No	Include full withheld-row detail. Defaults true with audit; explicitly set false only for a compact projection.

Output Schema

Name	Required	Description
`asOf`	No
`auth`	No	Credential lifetime visible to the caller. OAuth secondsRemaining lets an autonomous agent refresh before a multi-call workflow is interrupted.
`data`	No
`basis`	No
`claim`	No	Fahali dictionary claim (shared/fahaliDictionary.ts). Read `kind` FIRST: 'abstention' means no assertion was made and `reason` says why — never read an abstention as a neutral or zero result. `basis` says what the claim rests on: this tool is PROXY-derived and can never be 'measured'. Absent or null means this response path does not yet emit a claim; treat that as unknown, not as agreement.
`scope`	No
`trend`	No
`source`	No	Where the rows came from: market_wide_snapshot \| snapshot \| snapshot+inline \| inline; the default lower bound applied (crypto_30m \| session_96h \| market_wide_96h \| caller); and the refresher's snapshot meta (asOf, ageSeconds, stale, lastError, refreshIntervalSeconds).
`status`	No	The endpoint's original status vocabulary (for example ok, partial, degraded, withheld, or no_alerts). Use mcpStatus for normalized transport success/error.
`symbol`	No	Compatibility field, populated only for a one-symbol result.
`absence`	No	Why no actionable finding is present: measured_empty, user_empty, no_coverage, source_unverified, stale, withheld, source_error, auth_failure, or entitlement_required.
`summary`	No
`coverage`	No	Instruments this response can speak for, per asset class. Equities are watchlist-only: universe equities carry no bar timestamps and receive no flow row (nine names per session since at least 2026-09-14).
`decision`	No
`evidence`	No
`headline`	No
`conflicts`	No
`dataState`	No
`direction`	No
`freshness`	No	Over the rows with a write cadence (crypto, in-session equities): dataAsOf is the oldest such row; stale means a symbol stopped reporting against its own cadence. Last-session rows are excluded here and counted in lastSessionRows (2026-10-13).
`mcpStatus`	No	Normalized MCP result status. The endpoint's original status vocabulary remains in `status` and `sourceStatus`.
`requestId`	No
`confidence`	No	Compatibility alias for detectionScore. It is unusualness, not measurement presence and not a probability.
`dataOrigin`	No
`disclaimer`	No
`netFlowUsd`	No	Compatibility field for a one-symbol result. Null means no one-symbol observation; zero means a measured balanced window.
`provenance`	No
`claimPolicy`	No	Typed constraints for safe use. Metadata, not a prompt or instruction channel.
`instruments`	No	Resolved or explicitly partial instrument identities. A missing venue carries an ambiguity warning.
`limitations`	No
`nextActions`	No	Registry-validated follow-up calls. Missing tools, invalid arguments, unresolved placeholders, and disabled tools are omitted.
`notReturned`	No
`resolutions`	No
`sourceError`	No	The upstream endpoint's exact error text/code before normalization, when one was present.
`sourceScope`	No
`sourceStatus`	No	The upstream endpoint's exact status before the MCP envelope normalizes transport success/error.
`agentBriefing`	No	Audit-only narrative projection. Present only when detail='audit'; compact responses do not duplicate structured data as prose.
`claimValidity`	No	Validity of the selected binding claim only, calculated after filtering, projection and row selection. Sibling rows cannot determine it.
`responseState`	No
`schemaVersion`	No
`sourceDecision`	No
`symbolCoverage`	No	Conservation ledger satisfying requested = returned + withheld + notReturned for requested-symbol calls.
`evidenceQuality`	No
`lastSessionRows`	No	Rows served from a closed market's last session.
`responseControl`	No
`sourceDataState`	No	The upstream endpoint's exact data-state value before endpoint-aware classification.
`confidenceMeaning`	No
`recordMatchReason`	No	Why matchedTrackRecord is present or null. A null record is never evidence of safety or engine failure.
`matchedTrackRecord`	No	A judged record only when engine, horizon, regime/instrument class, and claim family match this response. `state` is one of: `measured` (a stratum cleared the publishability gate — `stratum` carries engine, horizon tier, bar regime, recall, precision, base rate, base-rate lift, median lead hours, effective sample, warned events and the measurement date); `withheld` (the gate ran and refused — `reason` says why, in words); `unavailable` (the record could not be read at all — an infrastructure failure that says nothing about the record). It is ONE stratum selected by recall, never a platform-wide accuracy. Null means no exact record match; read recordMatchReason.
`confidenceSemantics`	No	Every confidence-bearing value with its score type, scale, calibration status, and probability flag.
`decisionEligibility`	No	Fail-closed binding-authority policy. WITHHELD means source evidence remains available for audit while normalized direction, actionability and execution fields are revoked.
`trendWithheldReason`	No
`directionEligibility`	No	Current market-direction eligibility. Direction is authorized only by an exact, eligible producer stratum (canonical_verdict, canonical_symbol_verdict, committee_verdict) — read bindingAuthority to see which one bound. Widening WHO may bind did not weaken WHAT binding requires: the named producer must still hold a matching horizon/class/family record on a verified-only judged population, so an authority without a record still cannot bind.
`executionEligibility`	No	Fail-closed execution boundary. Portfolio monitoring tools always return WITHHELD with MONITOR_ONLY_NO_EXECUTION_AUTHORITY while Fahali has no capital path.
`freshnessByAssetClass`	No	crypto and equity blocks with the same shape as freshness; an equity block made only of last-session rows reports the age and stale: null, because a closed market has no cadence to be late against.
`monitoringEligibility`	No	Current portfolio-monitoring validity based on captured identity, freshness, integrity, and the caller-supplied monitoring policy. ELIGIBLE authorizes observation/delivery only, never financial action.
`sourceEvidenceQuality`	No
`currentActionEligibility`	No	Current eligibility of an immutable historical portfolio verdict. It never mutates the stored judgment being replayed.
`sourceConfidenceSemantics`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.28.1Oct 29, 2026
Removedv1.5.3Jul 25, 2026
First observedv1.0.0Jun 17, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety bar is low; the description nonetheless adds substantive traits: the data is a candle-derived proxy, lacks aggressor tape and participant identity, and carries no forecast. It also pre-empts a likely misread of the payload ('Zero detector score does not erase netFlowUsd: the score measures unusualness, not data presence'), which is exactly the kind of value beyond structured fields that matters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no waste, with the core capability front-loaded before the caveats. The zero-score caveat and the proxy-limitation sentence each carry distinct information an agent would otherwise have to discover empirically.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Return shape is covered by the output schema and safety by annotations, so the description's job is scope, defaults, and limits — all three are addressed. An agent can call it with no arguments, with symbols, and correctly interpret a zero score without further context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds the one thing the schema cannot convey — the semantic default when symbol/symbols are omitted (return the strongest available readings rather than nothing). It does not elaborate on limit/since/detail, but those are already fully documented in-schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific measurement (60-minute USD order-flow imbalance) with the resource (symbols) and its default fallback behavior, so the agent knows exactly what it is retrieving. The closing disclaimers ('candle-derived proxy only; no aggressor tape, fund-flow attribution') sharply separate it from attribution/forecast-style siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'or the strongest available readings when none are supplied' tells the agent it can call with zero arguments and what happens then, which is real usage guidance. However, it never names an alternative sibling (e.g. fahali_get_unusual_money_movement, fahali_get_microstructure_proxy) or states when to prefer this tool over them, so the when-to-use-vs-alternatives dimension is left implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server