Kirk — Unsupervised Structural Change Detection

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

Beyond the annotations, the description adds useful behavioral context: the tool costs 0 IU, is callable at zero balance, and is MCP-only. It also frames the action as a self-serve URL flow, consistent with readOnlyHint=false and openWorldHint=true. No contradictions with annotations, though it could mention potential errors or side effects.

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

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

The description uses labeled sections to deliver purpose, usage conditions, capability class, path fit, and cost in a compact format. Each section earns its place without redundancy or verbosity.

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

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

For a one-parameter billing tool with an output schema and basic annotations, the description provides complete operational context: when to use, when not to, cost, balance requirement, and the type of output (a URL). The output schema presumably describes the return value, so no further detail is needed.

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

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

The schema already provides 100% coverage for the single 'pack' parameter, including all three options and their pricing. The description's mention of the packs adds little beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool creates a Stripe Checkout Session URL for purchasing credit packs, and lists the three available packs. The verb 'create' plus the specific resource 'Stripe Checkout Session URL' makes the purpose unmistakable and distinguishes it from sibling billing tools like kirk_billing_show and kirk_billing_usage.

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

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

The description explicitly provides 'Use when' and 'Do not use when' conditions, including an alternative for enterprise deployments (invoiced directly). This gives the agent clear, actionable guidance on when to invoke this tool versus when to avoid it.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds no contradiction. It enriches this with zero-cost invocation, callable at balance=0, and the specific account state fields returned, which is useful behavioral context beyond annotations.

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

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

The description is well-structured with labeled sections and every line carries operational information: returns, use cases, exclusions, path fit, and cost. It is thorough without redundancy.

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

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

For a no-parameter, read-only tool with an existing output schema and clear annotations, the description covers when to use it, what it returns, cost behavior, and availability. No material gaps remain.

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

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

There are zero parameters, so there is nothing for the description to explain beyond the empty schema. The baseline of 4 applies because the schema fully covers the parameter surface.

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

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

The description opens with a specific verb ('Return') and enumerates the exact outputs: account_id, IU balance, USD equivalent, frozen flag, and recent ledger entries. This clearly distinguishes it from sibling billing tools and the inline `_cost` envelope.

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

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

Explicit 'Use when' and 'Do not use when' sections specify the intended scenarios (checking credit before large batch, debugging charges) and explicitly advise against using it for per-call cost, directing to the `_cost` envelope. It also clarifies the MCP-only path fit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds context: it is historical (not real-time), sourced from an append-only table, and useful for reconciling ledger debits. It also mentions a non-functional 'Cost: 0 IU' which adds mild context without contradicting annotations.

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

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

The description is well-structured with clear sections (purpose, use when, do not use when) and front-loads the core action. The extra metadata (Capability class, Path fit, Cost) is brief and not overly repetitive, though it could be trimmed without losing essential guidance.

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

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

Given the tool's simplicity (one optional parameter, read-only, with an output schema), the description fully covers what the tool does, when to use it, when not to, and the underlying data source. No critical behavioral information is missing.

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

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

The single `days` parameter is fully described in the schema ('window size (default 30)') with 100% coverage. The description's 'last N days' simply echoes the schema, adding no new semantic detail beyond the default value already present.

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

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

The description begins with a specific verb and resource: 'Return the caller's inference consumption over the last N days from the append-only Gate 2 events table.' It also clarifies the scope (per-tool breakdown) and distinguishes itself from real-time cost tools via the 'Do not use when' clause.

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

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

Explicit 'Use when' and 'Do not use when' sections provide clear context for when to invoke this tool versus alternatives like the `_cost` envelope on tool results. This gives direct guidance for an agent to choose correctly.

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

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

The annotations only indicate read-only, non-destructive, open-world behavior. The description adds substantial behavioral context: zero per-call LLM tokens, 0 IU cost, the return structure, and the fact that the returned client bills against the same underlying tools. This goes well beyond the annotations and gives the agent a clear model of what will happen.

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

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

The description is longer than average, but it is well-structured with labeled sections (Purpose, Use when, Do not use when, Cost, Return structure), making it scannable. Some cost-comparison details could be trimmed, but they serve to justify the tool's purpose.

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

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

For a zero-parameter tool that returns client code, the description is exceptionally complete: it covers purpose, usage thresholds, alternatives, cost behavior, return structure, and even deployment path. No important context is missing.

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

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

This tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters; instead, it enriches the output contract by listing exact return fields (language, filename, requirements, usage, code, example), which adds practical meaning.

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

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

The description opens with a specific, action-oriented statement: 'Return a self-contained stdlib Python client for scoring at ZERO per-call LLM tokens.' This clearly identifies the deliverable and its value proposition. It also distinguishes itself from sibling tools by naming conditions tied to kirk_score_book_batch and kirk_score_book.

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

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

The description provides explicit 'Use when' and 'Do not use when' sections with concrete thresholds (e.g., more than ~200 books, batch_too_large) and names the alternative simpler tool (kirk_score_book). This is exactly the kind of direct steering guidance expected.

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

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

Annotations already indicate read-only, open-world, non-destructive behavior. The description adds substantial context: it runs against the sealed engine, uses fixed synthetic jittered L2 snapshots, is rate-limited to 3/hour per IP, and returns per-regime statistics plus a representative pair. No contradiction with annotations.

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

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

The text is well-structured with labeled sections (Purpose, Use when, Do not use when, Cost, Returns) and a front-loaded summary. However, there is some redundancy: 'Free' appears both in the first sentence and in the Cost section, and the Purpose section partially restates the opening paragraph.

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

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

For a zero-parameter demo tool with an output schema, the description is complete. It covers when to use it, when not to use it, alternatives, cost, rate limits, behavior, and detailed output structure, leaving no significant gaps for a first-time caller.

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

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

The tool has zero parameters, so the baseline is 4. The description goes further by explicitly stating 'Zero arguments' and explaining that the input is a fixed synthetic representative pair, not a market feed, which clarifies why no parameters are needed and what the tool actually consumes.

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

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

The description opens with 'Runs a curated demonstration of Kirk on a trading example,' which specifies the verb, resource, and scope. It clearly distinguishes this demo from siblings by naming kirk_score_book and kirk_score_book_batch as the tools for scoring real data, and the trading focus separates it from kirk_demo_uav.

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

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

The 'Use when' and 'Do not use when' sections give explicit guidance: first-time callers exploring Kirk should use this, while those scoring their own data should use alternatives. It also mentions the rate limit and zero cost, providing concrete usage constraints.

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

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

The description goes far beyond the annotations by disclosing that the tool is free, rate-limited to 3/hour per IP, uses the same sealed engine, and returns real Kirk output. It also details the synthetic nature of inputs and the return contents, providing rich behavioral context beyond the readOnlyHint/destructiveHint annotations. No contradiction.

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

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

The description is long but well-structured with sections (Purpose, Use when, Do not use, Capability class, Cost, Returns). It front-loads the key summary in the first sentence and each subsequent section earns its place, though a slightly tighter presentation could improve scannability.

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

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

Given the tool has no input parameters and an output schema exists, the description is highly complete: it covers purpose, usage guidance, cost/rate limits, and details the return object fields (per-class statistics, z-separations, provenance, etc.). This gives the agent all necessary context for correct invocation and interpretation.

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

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

With zero parameters, the rubric gives a baseline of 4. The description reinforces this by stating 'Zero arguments' and clarifying that the inputs are fixed synthetic spectra baked into the demo, adding meaningful context about why no parameters are needed.

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

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

The description clearly states the tool runs a curated Kirk demonstration on a UAV example, with zero arguments, and distinguishes it from siblings like kirk_infer_legacy and kirk_demo_trading by emphasizing its demo nature and fixed synthetic inputs. It also conveys the purpose: first-time users can see what Kirk does before signing up.

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

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

Explicit 'Use when' and 'Do not use when' sections tell the agent to use this tool for cross-domain generalization demos without audio data, and to use kirk_infer_legacy directly for real feature vectors. This clearly differentiates from alternatives and prevents misuse.

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

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

The description adds significant behavioral context beyond the readOnlyHint and destructiveHint annotations: it discloses cost (1 IU per call, plus LLM token accrual), performance (millisecond-scale round-trip), and the sealed-engine attestation path. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then organized into labeled sections (Purpose, Use when, Do not use when, Capability class(es), Path fit, Cost). Every section adds distinct information without redundancy, making it efficient despite its length.

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

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

The description covers purpose, usage guidance, alternatives, cost, deployment options, and capability class. With an output schema present and rich annotations, there are no significant gaps for an AI agent to invoke the tool correctly.

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

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

The schema already fully describes the sole parameter 'values' as '50 floats' and explains the internal rendering. The description's first line reiterates '50-value feature vector' but does not add new semantic information. With 100% schema coverage, the baseline is 3.

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

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

The description opens with 'Score a 50-value feature vector against the legacy /v1/infer route on the sealed engine,' which is a specific verb ('Score') and resource ('feature vector','legacy /v1/infer route'). It further distinguishes itself from siblings by explicitly labeling it as 'legacy' and recommending kirk_score_book for fresh integrations.

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

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

The description includes explicit 'Use when' and 'Do not use when' sections, stating to use it for existing clients wired to /v1/infer and to avoid it for fresh integrations or tight loops, with named alternatives (kirk_score_book, kirk_bulk_howto). This is clear, actionable guidance with alternatives.

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

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

Annotations already mark readOnly/destructive hints, and the description adds engine-sha attestation, capability class C5, zero cost, and a same-binary-sha guarantee, going well beyond the structured fields. No contradiction.

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

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

Structured with short labeled sections, front-loaded purpose, and each line (use cases, exclusions, path fit, cost) carries distinct value. No redundant filler.

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

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

Covers purpose, use vs non-use, attestation behavior, cost, and integration path; output schema explains the return shape, so no gaps. The sibling context reinforces this is the discovery tool for the score_book family.

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

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

Tool has zero parameters and the input schema is fully self-contained (100% coverage), so baseline 4 applies; no parameter-level documentation is necessary or provided.

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

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

The opening sentence uses a specific verb ('Enumerate') and resource ('model_ids the sealed engine exposes'), immediately differentiating this catalog tool from inference/billing siblings. It also defines the response's attestation component.

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

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

Explicitly provides 'Use when' and 'Do not use when' conditions, including when wiring a client for score_book calls and when hyperparameter detail is needed. The path-fit note distinguishes MCP validation from production in-process use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it is prep-only, has zero cost (0 IU), and does not interact with the sealed engine or exercise any capability class beyond input-shape convention.

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

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

The description is longer than strictly necessary, but it is well-structured with clear sections (Purpose, Use when, Do not use when, Capability class, Path fit, Cost). The front-loaded first sentence carries the core meaning, and each subsequent section provides non-redundant useful context.

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

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

Given the tool's moderate complexity (2 params, output schema, annotations), the description goes beyond minimum requirements by explaining the tool's role in the broader workflow (validation via MCP vs. production attestation), cost implications, and exact exclusions (no scoring). It is complete and self-sufficient.

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

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

Schema description coverage is 100%, with clear descriptions for bid_px and ask_px. The description does not add parameter-level syntax but provides semantic context on how the arrays relate to the tensor convention (e.g., level 1 first, bid/ask levels), which is marginal added value over the schema.

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

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

The description states a specific verb ('Render') and resource ('L2 order-book snapshot into the 20×20 complex128 thermometer tensor') and explicitly notes that it does NOT invoke the sealed engine. This clearly distinguishes it from sibling scoring tools like kirk_score_book.

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

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

The description provides explicit 'Use when' scenarios (sanity-checking bid/ask level convention, inspecting cell patterns, debugging entropy values) and a 'Do not use when' clause naming kirk_score_book as the alternative for scoring. This is exemplary guidance.

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

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

Beyond the read-only/destructive annotations, the description discloses rate limits (60 req/min), cost (1 IU per call), millisecond-scale latency, bit-exact reproducibility, and sealed-engine attestation. This gives agents a comprehensive understanding of operational traits.

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

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

The description is well-structured with distinct sections (Purpose, Use when, Do not use when, Capability classes, Path fit, Cost). It is somewhat longer than minimal but every section provides relevant operational context, and the front-loaded summary sentence delivers the core purpose immediately.

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

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

The description covers the tool's input/output behavior, performance characteristics, cost, limitations, and relationships to sibling tools. It is complete for an interactive single-snapshot scoring use case, and the presence of an output schema means return value detail is not strictly required.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add parameter-specific details beyond what the schema already documents, which is acceptable but not additive.

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

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

The description clearly states the tool's function: 'Score one L2 order-book snapshot through the sealed single-layer path and return a scalar entropy plus engine attestation.' It uses specific verbs and resources, and distinguishes itself from siblings like kirk_score_book_batch by emphasizing single-snapshot scoring.

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

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

Explicit 'Use when' and 'Do not use when' sections provide clear guidance on when to invoke this tool versus alternatives. It explicitly directs users to kirk_bulk_howto for >200 books and notes that MCP is not for production or latency-critical work.

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

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

Even though annotations already mark readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: cost formula per 50 books, the exact error behavior for batches >500 ('batch_too_large' before any ledger debit), sealed-engine attestation, and reproducibility guarantees. No contradiction with annotations.

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

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

The description is longer than typical (about 200 words) but well-structured with clear headings (Purpose, Use when, Do not use when, Capability classes, Path fit, Cost). The main purpose is front-loaded in the first sentence. Each section earns its place given the tool's complexity, though some parts like 'Path fit' could be trimmed for an MCP tool.

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

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

The tool has an output schema, so return values need not be detailed, but the description covers limits, cost, error handling, alternatives, and reproducibility. It is fully sufficient for an agent to select and invoke the tool correctly, even with the rich set of sibling tools.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context around the 'books' parameter (e.g., max 500 and cost implications) but the schema already documents the list format and the batch_too_large error. No significant extra parameter-level meaning beyond what the schema provides.

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

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 up to 500 L2 order-book snapshots in one MCP call — returns an entropies list plus engine attestation.' This clearly states what the tool does and its scope (batch of up to 500), distinguishing it from siblings like kirk_score_book (single) and kirk_bulk_howto (bulk).

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

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

Explicit 'Use when' and 'Do not use when' sections provide clear context. The description names alternatives: kirk_bulk_howto for sustained bulk work, and notes the 500-book limit. This is textbook guidance on when to use this tool versus others.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: cost per invocation (1 IU), internal routing through kirk_score_book_batch with no double-metering, and the caveat that synthetic data should not appear in customer-visible results. This goes beyond what annotations provide and sets clear expectations.

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

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

The description is well-structured with clear sections (Purpose, Use when, Do not use when, Capability, Path fit, Cost) and front-loaded with the primary purpose. It is slightly longer than strictly necessary but every section provides distinct value, making it efficient rather than verbose.

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

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

For a tool with an output schema and rich annotations, this description is exceptionally complete: it covers purpose, usage alternatives, cost, internal routing, and restrictions. It explains the wrapper relationship and the non-production nature, leaving no critical gaps. The output schema handles return values, so the description's coverage is sufficient.

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

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

Schema description coverage is 100%, with each parameter (seed, model_id, n_samples) having clear descriptions and defaults. The description mentions 'N' in the text, aligning with n_samples, but adds no additional parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Synthesize N realistic-geometry L2 book snapshots and score them' and explicitly identifies it as a convenience wrapper on kirk_score_book_batch. This distinguishes it from siblings like kirk_score_book_batch (which scores real data) and provides a specific verb+resource+scope.

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

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

The description provides explicit 'Use when' and 'Do not use when' guidance, including use cases (wiring-check, first-integration walk-through) and exclusions (scoring anything real, synthetic bids/asks not for customer-visible results). It also names the alternative tool (kirk_score_book_batch) directly.

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

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

Annotations already mark read-only and non-destructive, but the description adds crucial behavioral nuance: the returned default engine sha may differ from the per-model engine sha, responses restate engine.sha, and non-2xx responses raise clean MCP errors. This goes well beyond annotation basics.

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

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

The description is front-loaded with the core purpose and organized into clear sections. It is longer than strictly necessary, with occasional repetition around liveness probing and cost, but the extra detail about engine sha provenance is valuable enough to justify the length.

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

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

Comprehensive for a zero-parameter, read-only tool. Covers purpose, liveness role, return fields, cost, error behavior, and the critical distinction between default and per-model engine hashes. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly focuses on return semantics and usage context instead of inventing parameter guidance.

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

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

States a precise action: verify sealed engine identity and return the sha256 of the running scoring binary. Clearly distinguishes itself from sibling scoring tools by emphasizing this is identity/liveness only and returns no entropies.

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

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

Explicitly provides 'Use when' and 'Do not use when' guidance, including when to record provenance and when to use it as a liveness check. It also names the scoring-result exclusion, which prevents confusion with kirk_score_* siblings.

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