Skip to main content
Glama
Sign In

NightWatch Live Intelligence

by io.github.jamboree777
OverviewDiscussionsAdmin

Publish a sized Forge signal

forge_signal_publish
Idempotent

Publish a SIZED signal on a Forge vault you operate (POST /forge/vaults/{vault_id}/signals). Requires vault_id, idempotency_key (becomes the signal's event_id; a retry with the same key and market returns the stored signal with idempotent_replay true), kind (open/rebalance/trim/universe), market (e.g. xyz:SKHX or main:BTC), side (buy/sell), target_weight (0..1 of a follower's NAV), target_leverage (at most the vault's leverage cap), ref_price, ref_price_source, reason, and rules_hash (the vault's CURRENT hash — read it from forge_signals; a stale one is refused with the current hash). A signal carries weights and leverage, never an absolute order size. Auth: your agent key (X-NW-User-Key, scope tx) when you are the vault's operator, OR an NTRT key — pass ntrt_id and ntrt_key — whose stall belongs to the same account as the vault. Refused if the vault is paused, a rule is broken, or the vault passed its hourly publish rate limit. Append-only: a published signal cannot be edited; publish a later one with supersedes_id. Off unless the deployment enables NW_FORGE_SIGNAL_PUBLISH_ENABLED.

Input Schema

NameRequiredDescriptionDefault
kindYes
sideYes
marketYese.g. xyz:SKHX or main:BTC
reasonYesWhy, in one or two sentences (max 500 chars)
ntrt_idNoOnly when authenticating with an NTRT key
ntrt_keyNoYour NTRT API key (nw_ntrt_...), instead of an agent key
vault_idYesForge vault id you operate
exec_specNoOptional: an execution spec v0 (check it first with strategy_spec_validate). Stored beside the signal with its spec_hash; the signal's market, side, target_weight and target_leverage must fit it; an invalid spec refuses the publish with the validator's errors
ref_priceYesReference price the signal was struck at
rules_hashYesThe vault's current rules_hash
supersedes_idNoOptional: id of an earlier signal on this vault this one replaces
target_weightYes0..1
idempotency_keyYesUnique per signal event, max 200 chars; reuse it to retry safely
target_leverageYes> 0 and at most the vault's leverage cap
ref_price_sourceYesWhere ref_price came from, e.g. hl_mark

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / exec_spec
      Added value: +{
+  "description": "Optional: an execution spec v0 (check it first with strategy_spec_validate). Stored beside the signal with its spec_hash; the signal's market, side, target_weight and target_leverage must fit it; an invalid spec refuses the publish with the validator's errors",
+  "type": "object"
+}
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations it discloses idempotent replay semantics (same key + market returns the stored signal with idempotent_replay true), both auth modes with header/scope details and the same-account constraint for NTRT keys, the append-only immutability rule, staleness rejection for rules_hash, and refusal conditions. It also states the semantic invariant that a signal carries weights and leverage, never an absolute order size.

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?

Purpose is front-loaded and the dense single paragraph is justified by the tool's complexity — auth, idempotency, refusals, and immutability all carry operational weight. It is long and clause-heavy, but almost no sentence is filler.

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?

For a 15-parameter mutation tool with no output schema, the description covers auth, idempotency, validation, refusal cases, feature-flag gating, and even the one observable return field (idempotent_replay). Nothing an agent needs to invoke it correctly is missing.

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 already 87%, but the description adds real meaning: idempotency_key becomes the signal's event_id, target_weight is a fraction of a follower's NAV, target_leverage is bounded by the vault's leverage cap, and rules_hash must be the vault's CURRENT hash or the call is refused with the current hash. Only exec_spec is left entirely to the schema text.

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 verb and resource ('Publish a SIZED signal on a Forge vault you operate') plus the route (POST /forge/vaults/{vault_id}/signals). The scope qualifier 'sized' and 'you operate' cleanly separates it from forge_signal_plan, forge_signal_fill, and forge_signals.

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?

Gives explicit when-to-use context (operating a vault, publishing a sized signal) and when-not (refused if paused, rule broken, or hourly rate limit exceeded; disabled unless NW_FORGE_SIGNAL_PUBLISH_ENABLED). It even routes to forge_signals for reading rules_hash and to supersedes_id instead of editing, but it never explicitly contrasts itself with the sibling forge_signal_plan or forge_signal_fill.

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

All NightWatch Live Intelligence toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources