Kirk — Unsupervised Structural Change Detection

Score L2 Order Books (v2 contract)

kirk_score_l2_book

Read-only

Score a sequence of full L2 order books as one chain and return per-book entropies plus engine attestation.

Purpose: Score complete books — prices, sizes and order counts — rather than prices alone. This is the v2 book contract; it carries information the price-only contract cannot.

STATE POLICY, and it matters: the books are scored IN ORDER as a single fresh chain. The model starts from its locked initial state at the first book and carries state forward across the rest, so a book's value depends on the books before it. State is never carried between calls. Sending the same books in a different order is a different measurement and will return different values; scoring N books one-per-call is NOT equivalent to one call of N books.

Use when: You are validating Kirk on full L2 snapshots. For the price-only v1 contract use kirk_score_book — the two are different envelopes and are not interchangeable.

Do not use when: You are looping this tool from an LLM. Call kirk_bulk_howto for bulk work; its v2 mode wraps this same call.

Cost: 1 IU per call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`books`	Yes	1..500 books, scored in the order given. Each book is an object with exactly eight fields: bid_px and ask_px (10 values each, level 1 = best quote, running outward), bid_quantity, ask_quantity, bid_num_orders, ask_num_orders (8 values each, same ordering), and bid_level_count, ask_level_count (scalars). Every value must be a finite JSON number; this contract does not impute or tolerate gaps.
`model_id`	No	A v2-contract model id. Defaults to kirk-l2-thermo-v2-e32-v1.	kirk-l2-thermo-v2-e32-v1

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 8, 2026

removedInput schema / properties / book

Removed value: -{
-  "additionalProperties": true,
-  "description": "One snapshot as a flat mapping of the envelope's columns to\nfloats. Prices are 10 levels per side (level 1 = best quote);\nsizes and order counts are 8 levels per side. Every column must be\npresent and finite — this envelope does not impute or tolerate\ngaps. Call kirk_list_models for the envelope hash.",
-  "type": "object"
-}

addedInput schema / properties / books

Added value: +{
+  "description": "1..500 books, scored in the order given. Each book is an object\nwith exactly eight fields: bid_px and ask_px (10 values each,\nlevel 1 = best quote, running outward), bid_quantity, ask_quantity,\nbid_num_orders, ask_num_orders (8 values each, same ordering), and\nbid_level_count, ask_level_count (scalars). Every value must be a\nfinite JSON number; this contract does not impute or tolerate gaps.",
+  "items": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "type": "array"
+}

changedInput schema / properties / model_id / description

Previous value: -"A v2-envelope model id. Defaults to kirk-l2-thermo-v2-e32-v1."New value: +"A v2-contract model id. Defaults to kirk-l2-thermo-v2-e32-v1."

changedInput schema / required

Previous value: -[
-  "book"
-]New value: +[
+  "books"
+]

AddedSep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The description clearly discloses the stateful chain behavior: books are scored in order as a single fresh chain, state is not carried between calls, and order matters. It also states the cost (1 IU per call) and reiterates non-interchangeability with the v1 contract. The readOnlyHint annotation is consistent with the scoring action.

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?

The description is well-structured with clear labeling (Purpose, State Policy, Use when, Do not use when, Cost). Some repetition of the state policy appears in multiple sections, but this is intentional to prevent misuse of the order-sensitive contract. Slightly verbose but acceptable given the critical caveats.

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?

The description covers the core purpose, usage boundaries, stateful behavior, cost, and parameter constraints. It mentions the return type (per-book entropies plus engine attestation) but does not detail the output schema; however, since an output schema exists, this is not a significant gap. The sibling-tool context further clarifies when this tool should be preferred.

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

Parameters5/5

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

The books parameter is described in detail: 1..500 books, exact field structure (bid_px, ask_px, quantities, order counts, level counts), ordering semantics, and the requirement that every value be a finite JSON number. model_id is defined with its default. Schema coverage is 100% and the description enhances it with concrete usage constraints.

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?

The description opens with a specific verb and resource: 'Score a sequence of full L2 order books as one chain and return per-book entropies plus engine attestation.' It explicitly distinguishes this v2 book contract from the price-only v1 contract, making the tool's unique purpose unmistakable.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool ('validating Kirk on full L2 snapshots'), when not to use it ('looping this tool from an LLM'), and directs users to kirk_bulk_howto for bulk work. It also contrasts with kirk_score_book, leaving no ambiguity about tool selection.

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

All Kirk — Unsupervised Structural Change Detection tools Inspect

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.