TypeScript SDK, MCP handler, examples, and receipt verifier for PERPBRAIN: read-only Hyperliquid data, a book simulator, and owner limits for AI agents. Simulation receipts are verified and reproducible: anyone can re-derive a receipt from its inputs and get the same hashes.
This repository has no mainnet order path, no exchange keys, and no publish workflow. Simulation output is labelled SIMULATED. It is not advice.
The PERPBRAIN hosted service and engine are not in this repository. This repository is the public client surface.
Path | Role |
|
|
| MCP JSON-RPC handler and stdio MCP server ( |
| MCP Registry metadata for |
| Slim Node image for Glama and other hosts; stdio entrypoint, non-root user. |
| Runnable TypeScript examples on recorded public data. |
| Browser receipt checker (WebCrypto SHA-256), the same check as the PERPBRAIN verify page. |
| Recorded public info responses and good and tampered receipt fixtures. No keys, no accounts. |
Related MCP server: hl-read
Node 22+ is required. No API key or other secret is needed for anything in this repository.
From a fresh clone:
git clone https://github.com/PERPBRAIN/perpbrain-sdk.git
cd perpbrain-sdk/ts/mcp-server && npm ci
cd ../..
node bin/perpbrain-mcp.mjsThe launcher starts the stdio MCP server. Live reads use the public Hyperliquid /info endpoint (mainnet by default). Optional: set PERPBRAIN_HL_NETWORK=testnet for testnet.
Equivalent from the repository root after npm ci in ts/mcp-server/:
node bin/perpbrain-sdk.mjs mcpTo work on the TypeScript SDK itself (not required for MCP-only use):
(cd sdk && npm ci && npm run build)@perpbrain/sdk is 0.1.0-rc1 and marked private in package.json, so it is not on npm yet. npm run build writes ESM and CommonJS builds to sdk/dist.
Each example runs offline on the files in fixtures/.
Check a receipt. VERIFIED means every hash re-derived from the inputs matches. A tampered fixture prints MISMATCH and names the field.
node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/good
node --experimental-strip-types examples/verify-receipt.ts fixtures/receipts/tampered-resultSimulate under the Standard preset, then see a looser leverage blocked before a fill is recorded:
node --experimental-strip-types examples/guarded-simulate.tsDrive the MCP handler with recorded public data. The tool list is read and simulation only, and submit_order is refused:
node --experimental-strip-types examples/mcp-fixtures.tsThe standalone MCP server uses the official @modelcontextprotocol/sdk over stdio. It is keyless: live reads use the public Hyperliquid /info endpoint only. Simulation uses the vendored book simulator. submit_order and other order tools are refused.
Simulation receipts are verified and reproducible. Owner limits are limits you set; losses are still possible.
Registry metadata lives in server.json (io.github.PERPBRAIN/perpbrain-sdk). For a step-by-step guide aimed at AI coding assistants (for example Cline), see llms-install.md.
Registered tool names, in list order:
Tool | Purpose |
| List perpetual markets from the public info endpoint. |
| Read a capped order book and its data age. |
| Read funding, mark, and open interest for one coin. |
| Read positions for one address. |
| Read the address fee rates and their data age. |
| Simulate a closed-bar decision on a supplied book. Result is SIMULATED. |
| Z-score of the public hourly funding rate against a trailing window. |
| Bid depth divided by ask depth inside a public-book band. |
| Read the owner limits and the remaining headroom. |
| Latch the kill switch. A tool call cannot clear it. |
| Recompute the execution-cost breakdown from a simulation receipt. The result is SIMULATED. |
| Check a simulation receipt against manifest and inputs bytes. The check is verified and reproducible. |
Add a server block (no API keys). Use absolute paths on your machine:
{
"mcpServers": {
"perpbrain": {
"command": "node",
"args": ["/absolute/path/to/perpbrain-sdk/bin/perpbrain-mcp.mjs"],
"env": {
"PERPBRAIN_HL_NETWORK": "mainnet"
}
}
}
}In Cursor Settings → MCP, add a server with the same shape (stdio, no secrets):
{
"mcpServers": {
"perpbrain": {
"command": "node",
"args": ["/absolute/path/to/perpbrain-sdk/bin/perpbrain-mcp.mjs"],
"env": {
"PERPBRAIN_HL_NETWORK": "mainnet"
}
}
}
}Replace /absolute/path/to/perpbrain-sdk with your clone path. Run cd ts/mcp-server && npm ci once before first use.
Serve verify/web/ with any static server and drop the three receipt files on the page.
import { GuardSession, guardedSimulate, verifyReceipt } from "@perpbrain/sdk";
const session = GuardSession.fromConfig("standard");
// guardedSimulate(...) records a fill only after the owner limits accept it.
// verifyReceipt(receipt, manifestBytes, inputsBytes) returns { status: "VERIFIED" | "MISMATCH", mismatches }.The read client only talks to the public /info endpoint, with an allowlist of request types. It refuses /exchange.
These are limits you set; losses are still possible. The owner picks a preset when a session starts. Standard is the default. Inside a session a caller can tighten a limit. A looser value is rejected. An MCP tool cannot set, raise, or clear a limit. Reducing or closing a position is never blocked. Details are in docs/guards.md.
Limit | Conservative | Standard (default) | Pro |
Max leverage, before the per-coin rule | 3x | 5x | 10x |
Per-order cap | Lesser of $10k and 20% of depth | Lesser of $25k and 20% of depth | Lesser of $250k and 20% of depth |
Daily stop | 3% | 5% | 10% |
Open positions | 3 | 5 | 15 |
Max slippage | 25 bps | 50 bps | 100 bps |
Order rate | 2/s | 5/s | 10/s |
Custom limits are capped at a 25% daily stop, 300 bps slippage, and 50 open positions.
Do not put exchange keys, wallets, or seed phrases in the environment, the repository, or a prompt. Nothing here reads them.
(cd ts/mcp-server && npm run lint && npm run typecheck && npm test)
(cd sdk && npm run typecheck && npm run build)
ts/mcp-server/node_modules/.bin/tsc -p examples/tsconfig.jsonCI runs the same checks plus a pinned gitleaks scan. CI uses no secrets.
Report a vulnerability as described in SECURITY.md. Contribution rules are in CONTRIBUTING.md.
MIT. See LICENSE.
Simulation only. Not advice. No live trading.
Bid depth divided by ask depth inside a public-book band.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and largely fails it: no data source, staleness, latency, market scoping, or whether the band is user-configurable. The only real disclosure is the formula itself, which is analytical rather than operational.
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?
A single front-loaded sentence with zero filler or redundancy. It is efficient, though the brevity is achieved by omitting necessary context rather than by tight writing.
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?
No annotations, no output schema, and an open input schema mean the description must supply the missing context, and it does not. It never states what is returned, which book/market is used, or how the band is determined, leaving an agent unable to call it confidently.
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?
Parameter count is zero, which normally gives a baseline of 4. But the schema sets additionalProperties=true with no documented properties, so the tool implicitly accepts inputs (e.g. symbol or band width) that neither the schema nor the description explains. The description mentions 'a public-book band' without saying how it is specified.
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 precise computation (bid depth / ask depth within a public-book band), so an agent can infer it returns an imbalance ratio. However it never says what the tool actually delivers (a number? a time series?) or what scope/market it applies to, unlike siblings such as order_book which are self-evident. Precise metric, vague deliverable.
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?
There is no when-to-use guidance and no reference to alternatives like order_book or markets for raw depth data. The reader must infer that this is a derived metric rather than a substitute for pulling the book itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the address fee rates and their data age.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. 'Read' implies a safe, read-only operation, but it says nothing about authentication, rate limits, caching, or whether the data is live or delayed beyond the vague mention of 'data age'.
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?
A single, front-loaded sentence with no wasted words. It communicates the core resource and a key output attribute without padding.
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 read tool with no output schema, the description is minimally adequate: it states what is read and notes that data age is included. Yet it lacks any usage context or differentiation from sibling tools that also relate to fees, leaving the agent to guess when this is the right call.
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 input schema defines zero parameters, so the baseline score of 4 applies according to the rubric. The description adds no parameter meaning because there are none to describe.
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 specific verb ('Read') and resource ('address fee rates and their data age'), so the core purpose is clear. However, it does not distinguish this tool from siblings like get_cost_breakdown or funding, which may also surface fee-related data.
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?
Provides no guidance on when to use this tool versus alternatives, nor any preconditions or context. It simply describes the action without indicating the scenario that selects it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read funding, mark, and open interest for one coin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It implies a read operation but says nothing about permissions, rate limits, data freshness, or response shape for a tool that returns three distinct metrics.
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?
A single sentence with no filler, and the core action and data types are front-loaded 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?
For a simple read tool this is minimally adequate, but with no output schema and no annotations, the description should clarify how the coin is specified and what the returned metrics represent. It leaves an agent to infer the input mechanism entirely.
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 exposes no parameters (0 params), so the baseline is 4. The description adds that the operation is for 'one coin,' but it never names the coin parameter or its expected format, leaving a gap that the schema also does not fill.
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 specific verb ('Read') and concrete resources (funding, mark, open interest) scoped to one coin. It does not name or contrast with the sibling funding_extremes, so sibling differentiation is left implicit.
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?
No when-to-use, when-not, or alternative-tool guidance is provided. The phrase 'for one coin' hints at single-coin scope but does not tell an agent when to choose this over markets, funding_extremes, or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Z-score of the public hourly funding rate against a trailing window.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the underlying data source ('public hourly funding rate') and a windowed statistic. But it omits crucial details like window length, whether it returns the z-score itself or the extreme event, and whether it's a computation or a filtered list. This is partial behavioral disclosure.
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?
Single sentence, no waste, front-loaded with the core concept.
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 with no output schema and no annotations, the description is minimal. It doesn't clarify the output (z-score value vs. list of extreme funding events), the window definition, or the time resolution beyond 'hourly'. An agent could invoke it but would be unsure what to expect.
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 0 parameters, so per the rules a baseline of 4 is appropriate. The description adds the semantic context of what the calculation represents, which is more than the empty 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 states a computation (z-score of public hourly funding rate against a trailing window), which is a specific formula-oriented output rather than a simple verb+resource. However, it's not framed as 'what the tool returns' or 'what action it performs' — it reads like a formula fragment. It doesn't differentiate from siblings like 'funding', which likely returns the raw rate.
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?
No indication is given for when to use this tool versus the sibling 'funding'. An agent would need to infer that this is the derivative/statistical version. No exclusions or alternatives cited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recompute the execution-cost breakdown from a simulation receipt. The result is SIMULATED.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that the output is SIMULATED, but says nothing about whether the call mutates state, what permissions it needs, whether recomputation is idempotent, or how the receipt is supplied to a tool with an empty input schema.
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?
Two short sentences, zero filler, and the core action is front-loaded with the simulated-output caveat immediately following. Every sentence earns its place.
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?
There is no output schema and no annotations, so the description must do more. Critically, it never explains how a 'simulation receipt' reaches a tool with an empty, additionalProperties-only input schema, leaving a real operational gap for the agent.
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 declares zero parameters and the schema is effectively empty at 100% coverage, so the baseline of 4 applies. The description adds no parameter detail, but there is nothing for it to describe.
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 specific verb+resource ('Recompute the execution-cost breakdown') and ties it to a source artifact ('from a simulation receipt'), which pins it down well. It does not, however, distinguish itself from nearby siblings like 'fees', 'simulate', or 'verify_receipt', so the agent must infer the difference.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The phrase 'from a simulation receipt' weakly implies it follows 'simulate', but this is inference rather than stated routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the owner limits and the remaining headroom.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It conveys read-only intent and the data returned, but does not disclose authentication requirements, rate limits, return format, or whether limits are account-specific. Minimal but not misleading.
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?
A single, front-loaded sentence with no wasted words. It states the action and the data directly, making it easy to scan and parse.
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 no output schema, the description should ideally explain return values or structure, but it only hints at them ('limits' and 'remaining headroom'). For a simple zero-param read, it is minimally adequate but leaves the agent without details on what the response contains or whether auth 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 tool has zero parameters, and the schema is an empty object. Per calibration, zero parameters yield a baseline of 4 even without additional description, since there are no parameter semantics to clarify.
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 specific verb 'Read' and resource 'owner limits and remaining headroom', which is clear enough for an agent to know what the tool does. However, it does not differentiate from siblings like fees or get_cost_breakdown, leaving that inference to the agent.
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 offers no indication of when to use this tool versus alternatives. There is no mention of prerequisites, context, or sibling tools, so the agent must guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List perpetual markets from the public info endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It notes that the data comes from a 'public info endpoint,' which implies a safe read operation with no auth, but it omits details like rate limits, pagination, or whether results are cached.
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 a single, front-loaded sentence with zero wasted words. It states the core action and data source 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?
Given the tool's low complexity (no parameters, no output schema, no annotations), the description is nearly complete for an agent to call it correctly. It could benefit from noting the response shape or scope (e.g., all perpetual markets vs. a subset), but nothing essential 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 there is no parameter semantics to clarify. The baseline score for zero-parameter tools is 4, and the description adds no misleading parameter information.
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 specific verb (List) and resource (perpetual markets), which clearly distinguishes it from most siblings focused on orders, funding, or positions. However, it does not explicitly differentiate itself from any particular sibling or clarify scope beyond 'public info endpoint'.
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 no when-to-use guidance, no alternatives, and no prerequisites. It only implies that this tool is for listing markets, leaving the agent to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a capped order book and its data age.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, but it only says the book is 'capped' and includes 'data age'. It does not clarify rate limits, auth requirements, how many levels are returned, or what 'data age' represents.
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 single sentence is front-loaded and free of padding. It is arguably too terse for behavioral context, but it is structurally efficient and wastes no words.
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 read tool with no output schema, the description states what is returned in broad terms but leaves key operational details missing. It does not explain scope (market/symbol), the cap size, or auth/rate constraints, so it is only minimally complete.
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 input parameters, and the schema contains no properties, so per the rubric the baseline is 4. The description appropriately adds no parameter guidance because none exist.
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 names a specific verb ('Read') and resource ('order book') and adds a notable return attribute ('data age'). It does not clearly differentiate from the sibling book_imbalance, and 'capped' is left undefined.
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?
There is no indication of when to use this tool versus alternatives such as markets or book_imbalance. The description supplies no context or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read positions for one address.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. "Read" implies read-only behavior, but the description omits authentication requirements, address-resolution mechanism, data freshness, pagination, and whether positions are spot, perpetual, or cross-margin.
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 single sentence is front-loaded and free of filler. It is appropriately brief, though the phrase "for one address" is somewhat unexplained given the empty parameter schema.
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?
With no annotations and no output schema, the description should explain what position data is returned and how the address is provided. It does neither, leaving an agent without enough context to invoke or interpret the tool confidently.
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 has zero parameters, which sets a baseline of 4. The description's "for one address" adds a scoping hint absent from the empty schema, though it also raises the unanswered question of how the address is supplied.
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 clear verb and resource: "Read positions." It is distinguishable from the market-data siblings, though the "for one address" scope is ambiguous because no address parameter appears in the schema.
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?
There is no explicit guidance on when to use this tool versus the eleven siblings, no prerequisites, and no exclusions. The phrase "for one address" implies context but does not tell an agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate a closed-bar decision on a supplied book. Result is SIMULATED.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose one important trait — the result is SIMULATED, implying a dry run with no real side effects — but says nothing about authentication needs, whether the simulation consumes live state, rate limits, or why the output is trustworthy.
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?
Two short sentences with no filler, and the scope ("closed-bar") is front-loaded ahead of the safety caveat. The brevity is efficient, though it verges on under-specification rather than tightness.
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?
With no annotations, no output schema, and an unconstrained input schema, the description is the only source of information and it does not supply enough: the decision being simulated, the book format, and the effects of running the tool all remain undefined.
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?
Zero declared parameters normally warrants a baseline of 4, but the schema sets additionalProperties=true with no properties, so the sole input hint is the phrase "a supplied book," whose shape and expected keys are never described. The description gestures at the input but leaves the agent without enough to construct a call.
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?
It names a specific verb ("Simulate") and an object ("a closed-bar decision on a supplied book"), which is more than a tautology. However, "closed-bar decision" is unexplained jargon and "supplied book" is never defined, so an agent cannot confidently distinguish the capability from siblings like book_imbalance or order_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?
There is no when-to-use statement, no prerequisites, and no named alternative among the twelve sibling tools. The only implicit guidance is that the result is not real, which is a behavioral trait rather than routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Latch the kill switch. A tool call cannot clear it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that a tool call cannot clear the kill switch, signaling irreversibility. However, it omits other critical behavior: what state changes occur, whether authentication or confirmation is required, and what the system does after latching.
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?
Two very short sentences with the most important fact (irreversibility) front-loaded. There is no filler, and every sentence adds essential information about the tool's behavior.
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 high-stakes, irreversible action with no annotations and no output schema, the description is too sparse. It does not explain what the kill switch stops, what side effects occur, or what safety checks may be needed, leaving significant gaps for an agent to safely invoke it.
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 parameter semantics are not a factor. The baseline of 4 applies because there is no schema parameter information that the description needs to supplement.
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 ('Latch') and resource ('the kill switch'), making the core action clear. However, it does not explain what the kill switch actually affects (e.g., halts trading, cancels orders, locks the system) or provide any sibling differentiation, leaving the full purpose partly opaque.
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 implies this is for an emergency latch, but it gives no explicit when-to-use guidance, no prerequisites, and no alternatives. An agent knows the action is irreversible but lacks context about when this should be invoked versus other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a simulation receipt against manifest and inputs bytes. The check is verified and reproducible.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Reproducible' hints at a deterministic, side-effect-free check, which is useful, but it never states failure behavior (error vs. mismatch result), whether it needs access to a manifest store, or what happens on a bad receipt. Significant gaps remain.
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?
Only two sentences and the purpose is front-loaded, which is good. The second sentence ('The check is verified and reproducible') is redundant self-description of verification and does not earn its place.
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 verification tool with no annotations and no output schema, the description should say what the caller receives (pass/fail, mismatch detail) and how the receipt/manifest are provided. Neither is covered, leaving the agent unable to predict the outcome of a call.
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?
Zero declared parameters gives the baseline of 4, and the description does add meaningful context by naming the three things involved: receipt, manifest, and input bytes. It does not explain how those are supplied or where the manifest comes from, but the schema itself is an open object, so there is little more to say.
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 first sentence names a specific verb and resource: checking a simulation receipt against a manifest and input bytes. That clearly ties it to the `simulate` sibling, so an agent can place it without opening the schema. However the second sentence ('The check is verified and reproducible') is tautological and adds no further distinguishing detail.
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?
There is no statement of when to invoke this versus `simulate` or any other sibling, and no prerequisite such as 'use after `simulate` produces a receipt'. Usage is only implied by the word 'receipt'. No exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0book_imbalancefeesfundingfunding_extremesget_cost_breakdownget_limitsmarketsorder_bookpositionssimulatetrigger_kill_switchverify_receiptScored across 12 tools
Most tools target clearly distinct reads (markets, order_book, positions, fees, get_limits) or distinct actions (simulate, trigger_kill_switch, verify_receipt). The main overlap risk is funding vs funding_extremes (raw read vs derived z-score) and order_book vs book_imbalance (raw book vs derived ratio), but the descriptions distinguish them well enough.
Conventions are mixed: bare nouns (markets, order_book, funding, positions, fees), noun+metric (funding_extremes, book_imbalance), get_-prefixed reads (get_limits, get_cost_breakdown), and imperative verbs (simulate, trigger_kill_switch, verify_receipt). Readable throughout, but there is no single predictable pattern.
12 tools is well-scoped for a perp/SDK surface covering market data, account reads, simulation, and risk controls. Each tool earns its place with no obvious redundancy.
Covers market data, account/position/fee/limit reads, simulation, cost breakdown, receipt verification, and a risk kill switch — a coherent analysis-and-simulation lifecycle. Gaps are minor and likely intentional (no order execution, and the kill switch is deliberately one-way with no clear/reset tool).
Non-custodial Hyperliquid perp trading: live markets, account state, user-armed order execution
Hyperliquid and Lighter market data: order books, trades, candles, funding, OI, and webhooks
Trade Papertrade BTC and ETH perps from Claude, ChatGPT, Codex, Cursor and any MCP client.
Hyperliquid MCP — read-only market data from Hyperliquid's public info API.
