Skip to main content
Glama
Sign In

TunnelMind Data API

by ai.tunnelmind
OverviewDiscussionsAdmin

ledger_search

One public search over the receipt sources, newest first. Not /v1/search (that is the domain search).

Use this tool when:

  • you want to find a TunnelMind change by ref, kind or summary.

  • you want one newest-first view of TunnelMind's changes and the attested tollbooth commons.

  • you want a past day's signed station-health rows (source=weather-health).

  • you want the roster of attested agent keys (source=agents).

Four public sources, and only these:

  • changes — the receipts ledger, lens config with change:* and toolset:* subjects (the same set as GET /v1/changes; a kind narrows it to one), mapped like GET /v1/changes so a row reads as a change, not a hash.

  • commons — tollbooth receipts from attested sites only.

  • weather-health — the signed station-health rows (lens wx-health), read from the public weather relay one CLOSED UTC day at a time. Every row is verified under the pinned weather key; a day that fails verification degrades the whole source. No row from the open (current) UTC day enters: the live 5-minute answer is station_health (GET /v1/weather/station/{icao}/health).

  • agents — the attested agent-key roster (tollbooth_agent_facts, attested sites only): one row per verified agent key, summed over its isolates and placed at the key's newest snapshot. A roster of keys, not receipts: each row points at the per-key record GET /v1/tollbooth/agents/{key} (the row's id), which names the signed snapshots behind the sums.

The default view (no source) is changes + commons only and makes no relay call; weather-health rows appear only with source=weather-health, agents rows only with source=agents.

API-verdict receipts (cross_lens, preflight, scry, self, …) are NOT public: ADR-010 keeps them hashes-only, so they are not in this ledger. The weather-health rows are not API-verdict receipts: they are TunnelMind's own judgements over public NWS observations, already public on the relay.

Searchable, NOT downloadable: limit is at most 100, there is no NDJSON, no format= and no day dump. Bulk goes through the tollbooth export. Changes rows carry public fields only — no receipt body, no customer_id. Commons rows carry the signed tollbooth document verbatim (receipt, or receipt_unreadable: true when the stored document does not parse). Weather-health rows carry the signed health receipt verbatim (receipt) with its day, station, verdict, rules_version and chain sequence. Agents rows carry the key (id), its newest ua, and the summed requests and isolates counts.

Each source is read and degraded on its own: sources.<name>.coverage is observed_clean, never_observed (an honest absence, e.g. day= the open day, or no closed day published yet; with a reason) or degraded with a reason. A degraded source contributes no rows; the response is still 200, never a crash and never an empty list passed off as clean. Only the sources the filters can match are listed.

Paging: truncated is true when more rows exist; pass next_cursor as cursor for the next page. Rows are ordered by issued_at (newest first), then source (changes, then commons, then weather-health, then agents), then id, and the cursor marks the last row returned, so rows sharing a timestamp are never skipped or repeated.

400 invalid_request on a malformed q, source, kind, day, before, cursor or limit (including source=receipts), on cursor with before, and on kind with source=commons, source=weather-health or source=agents.

?receipt=true attaches a signed Receipt v1.0 over the result. It is not written to the receipts ledger (receipt_logged: false): the rows are already signed at source, and logging each search would feed the changes source.

Rate limits: anonymous: 10 per minute per IP; no daily cap on /v1/self, /v1/pricing, /v1/ledger and /v1/weather/station/{icao}/health; other anonymous probes 100 per day; free tier 50 per day. For anonymous callers this route has no daily cap and keeps 10/min; API-key tiers keep their daily cap.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ledger_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSubstring to match (changes — subject or summary; commons — path class; weather-health — station or flag id; agents — the ua, any case, or a key prefix, exact case). 0-100 chars of letters, digits, space and `._:/#@-`.
dayNoOnly rows issued on this UTC day (YYYY-MM-DD). Not in the future.
kindNoOnly changes of this kind. Applies to the `changes` source only.
limitNoMaximum rows returned, 1-100.
beforeNoOnly rows strictly older than this ISO 8601 instant (timezone required). A time filter, not a paging cursor; cannot be combined with `cursor`.
cursorNoOpaque paging cursor: pass `next_cursor` from the previous page, unchanged, with the same other filters. 1-256 base64url characters encoding JSON `{t, s, i}` (the last row's issued_at, source and id); anything else, or `cursor` with `before`, is a 400.
sourceNoOnly this source. Omit for the default view, `changes` + `commons` (weather-health and agents only when asked for).
receiptNoWhen true, attach a signed Receipt v1.0 over the result (not logged to the receipts ledger). Additive — a signing failure never costs you the observation (ADR-014).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / q / description
      Previous value: -"Substring to match (changes — subject or summary; commons — path class; weather-health — station or flag id). 0-100 chars of letters, digits, space and `._:/#@-`."New value: +"Substring to match (changes — subject or summary; commons — path class; weather-health — station or flag id; agents — the ua, any case, or a key prefix, exact case). 0-100 chars of letters, digits, space and `._:/#@-`."
    • changedInput schema / properties / source / description
      Previous value: -"Only this source. Omit for the default view, `changes` + `commons` (weather-health only when asked for)."New value: +"Only this source. Omit for the default view, `changes` + `commons` (weather-health and agents only when asked for)."
    • changedInput schema / properties / source / enum
      Previous value: -[
-  "changes",
-  "commons",
-  "weather-health"
-]New value: +[
+  "changes",
+  "commons",
+  "weather-health",
+  "agents"
+]
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses per-source degradation states (`observed_clean`/`never_observed`/`degraded`), that degraded sources return 200 with no rows rather than crashing, the exact 400 triggers, rate limits by tier, and that `receipt=true` is not logged (`receipt_logged: false`). Nothing an agent needs to predict behavior is hidden.

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

Conciseness3/5

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

Well organized and front-loaded with the one-liner and use-case list, but it sprawls to ~700 words with repeated material (weather-health explained in the source list and again in the default-view paragraph) and a trailing rate-limit paragraph that is only marginally decision-relevant. Structure is good; economy is not.

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

Completeness5/5

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

For a four-source, paging, degradation-aware tool with no output schema, the description supplies row shapes per source, ordering and cursor semantics (including tie-breaking so rows are never skipped), and coverage semantics. An agent can call it correctly and interpret the response without further documentation.

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

Parameters4/5

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

Schema coverage is 100% and the schema already documents each parameter well, so baseline is 3; the description adds cross-parameter constraints the schema does not fully state (the enumerated 400 set including `source=receipts`, `kind` rejected with commons/weather-health/agents). Its additions are real but mostly restate schema-level facts rather than extending them.

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?

Opens with a specific verb and resource ("One public search over the receipt sources, newest first") and immediately disambiguates from the sibling domain search ("Not `/v1/search`"). It also enumerates the exact source set, so an agent knows precisely what universe of data is being searched.

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?

Provides an explicit "Use this tool when:" list with four concrete intents, plus negative routing: live station health goes to `station_health`, bulk goes to `tollbooth_export`, and API-verdict receipts are intentionally absent. Alternatives and exclusions are both named.

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

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources