fahali-mcp

fahali_get_portfolio_risk

Read-onlyIdempotent

Measure connected-book risk with VaR, expected shortfall, and per-position monitoring evidence. Returns stateless risk data without binding actions, pointing to the mandate-aware decision tool.

Instructions

Measured connected-book risk, VaR/expected shortfall, canonical covariance, and per-position monitoring evidence. Direction belongs to the canonical symbol verdict; this stateless surface withholds binding actions and points to the mandate-aware portfolio decision tool.

Input Schema

Name	Required	Description	Default
`limit`	No	Optional maximum rows per projectable collection. Audit has no MCP projection cap; brief defaults to 3 and standard to 12.
`since`	No	Optional lower timestamp bound for returned row collections.
`detail`	No	Response depth. audit is the full-fidelity default; brief and standard are explicit compact projections.	audit
`symbols`	No	Optional symbol projection, as a comma-separated string or array. Rows without instrument identity are not discarded.
`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.
`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. Absent or null means this response path does not yet emit a claim; treat that as unknown, not as agreement.
`scope`	No
`status`	No	The endpoint's original status vocabulary (for example ok, partial, degraded, withheld, or no_alerts). Use mcpStatus for normalized transport success/error.
`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.
`decision`	No
`conflicts`	No
`dataState`	No
`mcpStatus`	No	Normalized MCP result status. The endpoint's original status vocabulary remains in `status` and `sourceStatus`.
`portfolio`	No
`positions`	No
`requestId`	No
`timestamp`	No
`claimPolicy`	No	Typed constraints for safe use. Metadata, not a prompt or instruction channel.
`correlation`	No
`instruments`	No	Resolved or explicitly partial instrument identities. A missing venue carries an ambiguity warning.
`nextActions`	No	Registry-validated follow-up calls. Missing tools, invalid arguments, unresolved placeholders, and disabled tools are omitted.
`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.
`contagionRisk`	No
`responseState`	No
`schemaVersion`	No
`sourceDecision`	No
`symbolCoverage`	No	Conservation ledger satisfying requested = returned + withheld + notReturned for requested-symbol calls.
`evidenceQuality`	No
`responseControl`	No
`sourceDataState`	No	The upstream endpoint's exact data-state value before endpoint-aware classification.
`decisionAuthority`	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.
`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.
`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.

Changed6 schema fields changedv1.28.1Oct 29, 2026

addedInput schema / properties / detail

Added value: +{
+  "default": "audit",
+  "description": "Response depth. audit is the full-fidelity default; brief and standard are explicit compact projections.",
+  "enum": [
+    "brief",
+    "standard",
+    "audit"
+  ],
+  "type": "string"
+}

addedInput schema / properties / include_withheld

Added value: +{
+  "default": true,
+  "description": "Include full withheld-row detail. Defaults true with audit; explicitly set false only for a compact projection.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Optional maximum rows per projectable collection. Audit has no MCP projection cap; brief defaults to 3 and standard to 12.",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / since

Added value: +{
+  "description": "Optional lower timestamp bound for returned row collections.",
+  "format": "date-time",
+  "type": "string"
+}

addedInput schema / properties / symbols

Added value: +{
+  "description": "Optional symbol projection, as a comma-separated string or array. Rows without instrument identity are not discarded.",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "string",
+    "array"
+  ]
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "absence": {
+      "description": "Why no actionable finding is present: measured_empty, user_empty, no_coverage, source_unverified, stale, withheld, source_error, auth_failure, or entitlement_required.",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "agentBriefing": {
+      "description": "Audit-only narrative projection. Present only when detail='audit'; compact responses do not duplicate structured data as prose.",
+      "type": "string"
+    },
+    "asOf": {
+      "format": "date-time",
+      "type": "string"
+    },
+    "auth": {
+      "description": "Credential lifetime visible to the caller. OAuth secondsRemaining lets an autonomous agent refresh before a multi-call workflow is interrupted.",
+      "properties": {
+        "credentialType": {
+          "enum": [
+            "oauth",
+            "api_key",
+            "process_key",
+            "none"
+          ],
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "refreshSupported": {
+          "type": "boolean"
+        },
+        "secondsRemaining": {
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "claim": {
+      "description": "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. Absent or null means this response path does not yet emit a claim; treat that as unknown, not as agreement.",
+      "properties": {
+        "basis": {
+          "enum": [
+            "measured",
+            "proxy",
+            "derived",
+            "absent"
+          ],
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "observation",
+            "estimate",
+            "forecast",
+            "recommendation",
+            "abstention"
+          ],
+          "type": "string"
+        },
+        "reason": {
+          "description": "Required when kind is 'abstention'. Written for a reader, not a log.",
+          "type": "string"
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "claimPolicy": {
+      "description": "Typed constraints for safe use. Metadata, not a prompt or instruction channel.",
+      "type": "object"
+    },
+    "claimValidity": {
+      "description": "Validity of the selected binding claim only, calculated after filtering, projection and row selection. Sibling rows cannot determine it.",
+      "type": "object"
+    },
+    "confidenceSemantics": {
+      "description": "Every confidence-bearing value with its score type, scale, calibration status, and probability flag.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "conflicts": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "contagionRisk": {
+      "type": "object"
+    },
+    "correlation": {
+      "type": "object"
+    },
+    "currentActionEligibility": {
+      "description": "Current eligibility of an immutable historical portfolio verdict. It never mutates the stored judgment being replayed.",
+      "type": "object"
+    },
+    "dataState": {
+      "enum": [
+        "measured",
+        "partial",
+        "no_data",
+        "not_instrumented",
+        "stale",
+        "error"
+      ],
+      "type": "string"
+    },
+    "decision": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "decisionAuthority": {
+      "type": "object"
+    },
+    "decisionEligibility": {
+      "description": "Fail-closed binding-authority policy. WITHHELD means source evidence remains available for audit while normalized direction, actionability and execution fields are revoked.",
+      "type": "object"
+    },
+    "directionEligibility": {
+      "description": "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.",
+      "type": "object"
+    },
+    "evidenceQuality": {
+      "type": "object"
+    },
+    "executionEligibility": {
+      "description": "Fail-closed execution boundary. Portfolio monitoring tools always return WITHHELD with MONITOR_ONLY_NO_EXECUTION_AUTHORITY while Fahali has no capital path.",
+      "type": "object"
+    },
+    "instruments": {
+      "description": "Resolved or explicitly partial instrument identities. A missing venue carries an ambiguity warning.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "matchedTrackRecord": {
+      "description": "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.",
+      "properties": {
+        "dataAsOf": {
+          "description": "When the record was computed. A figure without this reads as current forever.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present on `withheld` and `unavailable`: why there is no figure.",
+          "type": "string"
+        },
+        "state": {
+          "enum": [
+            "measured",
+            "withheld",
+            "unavailable"
+          ],
+          "type": "string"
+        },
+        "stratum": {
+          "description": "Present only on `measured`. Precision must never be quoted without recall.",
+          "properties": {
+            "barRegime": {
+              "type": "string"
+            },
+            "baseRatePct": {
+              "type": "number"
+            },
+            "claimFamily": {
+              "description": "What this precision is ABOUT: `directional` (price moved the way the stratum said) or `magnitude` (a move exceeded the judge bar, carrying no direction). Never infer a direction from a `magnitude` row.",
+              "type": "string"
+            },
+            "claimMeans": {
+              "description": "The record endpoint's own sentence explaining the claim family. Quote it beside any precision figure.",
+              "type": "string"
+            },
+            "effectiveSample": {
+              "type": "number"
+            },
+            "engine": {
+              "type": "string"
+            },
+            "horizonTier": {
+              "type": "string"
+            },
+            "leadMedianHours": {
+              "type": "number"
+            },
+            "measuredOn": {
+              "type": "string"
+            },
+            "precisionPct": {
+              "description": "Share of its warnings that held. Never quotable alone.",
+              "type": "number"
+            },
+            "recallPct": {
+              "description": "Share of qualifying events this stratum warned on — the half a buyer is exposed to.",
+              "type": "number"
+            },
+            "warnedEvents": {
+              "type": "number"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "state"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "mcpStatus": {
+      "description": "Normalized MCP result status. The endpoint's original status vocabulary remains in `status` and `sourceStatus`.",
+      "enum": [
+        "ok",
+        "error"
+      ],
+      "type": "string"
+    },
+    "monitoringEligibility": {
+      "description": "Current portfolio-monitoring validity based on captured identity, freshness, integrity, and the caller-supplied monitoring policy. ELIGIBLE authorizes observation/delivery only, never financial action.",
+      "type": "object"
+    },
+    "nextActions": {
+      "description": "Registry-validated follow-up calls. Missing tools, invalid arguments, unresolved placeholders, and disabled tools are omitted.",
+      "items": {
+        "properties": {
+          "args": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "requiredTier": {
+            "type": "string"
+          },
+          "tool": {
+            "type": "string"
+          },
+          "why": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "tool",
+          "why"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "portfolio": {
+      "properties": {
+        "cashBalance": {
+          "type": "number"
+        },
+        "expectedDrawdownPct": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "expectedShortfall95": {
+          "description": "Expected shortfall at 95% in currency, positive for a loss. Reported in dollars as well as percent because the percent field is rounded at 0.01pp.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "expectedShortfallAttribution": {
+          "description": "Which holdings the expected shortfall is attributable to. Contributions are SIGNED, so a hedge that pays in the tail reports a negative number; componentSumDollars equals the reported expected shortfall exactly. Null when the figures are null.",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "grossExposure": {
+          "type": "number"
+        },
+        "grossExposureMetric": {
+          "type": "object"
+        },
+        "leverage": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "overallRiskLevel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "overallRiskScore": {
+          "description": "0-1 scale; null when detection evidence does not cover the book.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "riskMetricsBasis": {
+          "type": "object"
+        },
+        "totalValue": {
+          "type": "number"
+        },
+        "totalValueMetric": {
+          "type": "object"
+        },
+        "valueAtRisk95": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "varBacktest": {
+          "description": "Out-of-sample coverage test of the VaR quantile (Kupiec + Christoffersen), with the sample size stated. 'not_rejected' means the sample did not contradict the model, never that it is correct. Tests the quantile only, not expected shortfall.",
+          "type": [
+            "object",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "positions": {
+      "items": {
+        "properties": {
+          "authorityReconciliation": {
+            "description": "Canonical-symbol direction plus explicitly withheld stateless portfolio actionability and non-binding compatibility monitoring.",
+            "type": "object"
+          },
+          "correlationBasis": {
+            "type": "object"
+          },
+          "correlationToPortfolio": {
+            "description": "Always null: the artifact has pair correlations but not the variances/covariances required for corr(asset, portfolio return).",
+            "type": "null"
+          },
+          "correlationToPortfolioUnavailableReason": {
+            "type": "string"
+          },
+          "recommendation": {
+            "description": "Deprecated compatibility monitoring label; never a direction or authorized action.",
+            "properties": {
+              "action": {
+                "enum": [
+                  "hold",
+                  "watch",
+                  "reduce"
+                ],
+                "type": "string"
+              },
+              "binding": {
+                "enum": [
+                  false
+                ],
+                "type": "boolean"
+              },
+              "deprecatedSemantics": {
+                "enum": [
+                  "monitoring_priority_only"
+                ],
+                "type": "string"
+              },
+              "directional": {
+                "enum": [
+                  false
+                ],
+                "type": "boolean"
+              },
+              "rationale": {
+                "type": "string"
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "riskObservation": {
+            "type": "object"
+          },
+          "riskScore": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "symbol": {
+            "type": "string"
+          },
+          "weightedMeanPeerCorrelation": {
+            "description": "Gross-weighted mean of measured pairwise Pearson correlations to peer holdings; not corr(asset, portfolio return).",
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "recordMatchReason": {
+      "description": "Why matchedTrackRecord is present or null. A null record is never evidence of safety or engine failure.",
+      "type": "string"
+    },
+    "requestId": {
+      "type": "string"
+    },
+    "responseControl": {
+      "type": "object"
+    },
+    "responseState": {
+      "enum": [
+        "OK_WITH_FINDINGS",
+        "OK_NO_FINDINGS",
+        "PARTIAL",
+        "WITHHELD",
+        "NO_COVERAGE",
+        "ERROR"
+      ],
+      "type": "string"
+    },
+    "schemaVersion": {
+      "enum": [
+        "2.0"
+      ],
+      "type": "string"
+    },
+    "scope": {
+      "type": "object"
+    },
+    "sourceConfidenceSemantics": {
+      "type": [
+        "array",
+        "object",
+        "null"
+      ]
+    },
+    "sourceDataState": {
+      "description": "The upstream endpoint's exact data-state value before endpoint-aware classification.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "sourceDecision": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "sourceError": {
+      "description": "The upstream endpoint's exact error text/code before normalization, when one was present.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "sourceEvidenceQuality": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "sourceScope": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "sourceStatus": {
+      "description": "The upstream endpoint's exact status before the MCP envelope normalizes transport success/error.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "The endpoint's original status vocabulary (for example ok, partial, degraded, withheld, or no_alerts). Use mcpStatus for normalized transport success/error.",
+      "type": "string"
+    },
+    "symbolCoverage": {
+      "description": "Conservation ledger satisfying requested = returned + withheld + notReturned for requested-symbol calls.",
+      "type": "object"
+    },
+    "timestamp": {
+      "type": [
+        "string",
+        "integer",
+        "number"
+      ]
+    }
+  },
+  "type": "object"
+}

First observedv1.0.0Jun 17, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description still adds meaningful context beyond them: the surface is stateless and withholds binding actions, telling the agent this is measurement-only. It doesn't discuss cost, rate limits, or staleness of risk figures.

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

Conciseness4/5

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

Two sentences with no filler, and the core capability is front-loaded before the boundary/routing statement. Slight density of unexplained domain terms costs a point but every clause carries information.

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

Completeness4/5

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

An output schema exists, so return values need not be described, and the description covers purpose, boundaries, and safe-use context. What remains missing is a positive usage trigger and any note on data freshness of the risk figures, which matters for a risk surface.

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

Parameters3/5

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

Schema description coverage is 100%, so all five parameters (limit, since, detail, symbols, include_withheld) are already documented with defaults, enums, and bounds. The description adds no parameter guidance of its own, so the baseline of 3 applies.

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

Purpose4/5

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

States specific resources: connected-book risk, VaR/expected shortfall, covariance, and per-position monitoring evidence. It distinguishes itself from the canonical symbol verdict surface and names the portfolio decision tool as the action-capable sibling. The term 'connected-book' and 'canonical covariance' are opaque jargon, keeping it from a 5.

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

Usage Guidelines4/5

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

Explicitly routes two alternatives: direction queries belong to the canonical symbol verdict, and binding actions belong to the mandate-aware portfolio decision tool. It doesn't state a positive trigger condition (when an agent should reach for risk measurement), so it falls just short of full when/when-not coverage.

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

Deploy Server