fahali-mcp

fahali_create_alert

Creates a custom agent alert for the in-app realtime feed, marked with an agent prefix and capped at high severity so it stays separate from engine detections and avoids push/SMS.

Instructions

Create a custom alert. Agent-created alerts appear in the in-app realtime feed, hard-marked with an agent_ type prefix so they are never confused with engine detections; they do not trigger push/SMS to other users, and severity is capped at high (critical is reserved for engines).

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
`symbol`	Yes	Trading symbol (e.g. 'BTCUSDT').
`message`	Yes	Human-readable alert message.
`symbols`	No	Optional symbol projection, as a comma-separated string or array. Rows without instrument identity are not discarded.
`severity`	Yes	Severity level. `critical` is intentionally not offered: the upstream caps it to `high` (critical fans out to holder SMS/email and is reserved for engines), so asking for it would store something other than what was requested.
`alert_type`	Yes	Alert classification (e.g. 'agent_insight', 'custom_pattern').
`confidence`	No	Confidence score 0-1 (optional, default 0.5).
`idempotency_key`	No	Stable retry key. Repeating the same key returns the original alert instead of creating a duplicate.
`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.
`alert`	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. 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.
`success`	No
`decision`	No
`conflicts`	No
`dataState`	No
`mcpStatus`	No	Normalized MCP result status. The endpoint's original status vocabulary remains in `status` and `sourceStatus`.
`requestId`	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.
`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.
`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.
`idempotentReplay`	No	True when this idempotency key already created an alert and the original was returned.
`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.

Addedv1.28.1Oct 29, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Goes well beyond the annotations by disclosing real side effects: alerts surface in the in-app realtime feed, are prefixed with agent_ so they cannot be mistaken for engine detections, do not fan out to push/SMS, and severity is capped at high. This is exactly the kind of consequence an agent needs before writing. It omits the idempotency_key retry behavior, which lives only in the schema, and does not describe what the call returns.

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?

A single compact paragraph with the core action front-loaded and each clause carrying distinct behavioral content (feed visibility, prefix, no push/SMS, severity cap). Dense but no filler; slightly long as one unbroken sentence.

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?

With 11 parameters at full schema coverage and an output schema present, the description does not need to explain params or return values. It covers the key behavioral risks (visibility, notification fan-out, severity ceiling) well; the only meaningful gap is the absence of usage routing toward related read tools.

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 parameters are already fully documented, including the severity enum rationale and idempotency_key semantics. The description restates the severity cap that the schema also explains, adding emphasis but not new parameter-level information. Baseline 3 is appropriate.

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?

Opens with a specific verb and resource: 'Create a custom alert.' That is unambiguous and distinguishable from the read-only alert siblings such as fahali_get_realtime_alerts. It stops short of naming alternatives or stating scope constraints an agent would use for routing.

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?

Usage is implied by 'Create a custom alert' and the agent-oriented framing, but there is no explicit when-to-use / when-not-to-use guidance, no mention of prerequisites, and no routing to sibling tools (e.g. reading alerts via fahali_get_realtime_alerts). An agent can infer intent but is not steered.

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

Deploy Server