Moved to com.steledger/gateway — same service, now at https://api.steledger.com/mcp
Scored across 9 tools
Each tool maps to a distinct operation: enumeration (list_records) vs single fetch (read_record), single write (store_memory) vs bulk write (store_memory_batch), and clearly separate concerns for identity (register_identity, whoami), chain health (node_status), transfer (transfer_records) and support (send_feedback). The only near-neighbours, store_memory and store_memory_batch, are explicitly contrasted (one transaction, all-or-nothing, N writes).
Seven of nine tools follow a clear verb_noun snake_case pattern (list_records, read_record, register_identity, store_memory, transfer_records, send_feedback). node_status and whoami are noun-only/idiomatic outliers, but they remain unambiguous and readable rather than inconsistent in style.
Nine tools is well within the sweet spot and each earns its place: two read paths, two write paths, identity/session, chain health, transfer, and a feedback escape hatch. Nothing feels redundant or bolt-on.
The lifecycle is largely covered: discover your id (whoami), register, write singles and batches, list, read, and hand off custody (transfer_records), with node_status supporting expiry interpretation. Gaps are minor — there is no way to look up records by content hash across identities and no explicit renewal/expiry-extension tool beyond re-storing the same hash.
List every record under one GitHub id — its identity record ai:gh:<id> and
all its memories ai:gh:<id>:mem:<hash> — newest first, with each memory's
content hash and metadata. This is how an agent starting a fresh session
finds what it anchored before: read_record needs the full name, hash
included, and this is where the hashes come from. Read-only, no sign-in
needed to list any id; omit github_id to list your own when signed in.
What comes back is the chain's view: confirmed records only (a write still in
the mempool shows up after its block), expired ones included and flagged
expired — their names can be taken by someone else, so do not treat them
as yours. Only fingerprints and metadata live here; the content itself stays
wherever you stored it. Results are cached for about a minute, so a record
confirmed seconds ago may take that long to appear.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1–200. | |
| offset | No | Where the page starts; use `next_offset` from the previous page. | |
| github_id | No | Numeric GitHub id whose records to list. Omit it to list your own (needs a signed-in session; `whoami` shows the id). |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| offset | Yes | |
| records | Yes | |
| github_id | Yes | |
| next_offset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/open-world, but the description adds substantive traits the annotations cannot convey: confirmed-block records only (mempool writes lag), expired records included and flagged with the warning that their names can be reclaimed, and roughly one-minute result caching. It also clarifies that only fingerprints and metadata are returned, never content.
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 opening clause front-loads verb, resource, and return shape before any caveats, and every subsequent sentence carries real information. It is on the long side and the 'Read-only, no sign-in needed' phrase partly restates the readOnlyHint annotation, which costs a bit of density.
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 an output schema present, the description needn't enumerate return fields, yet it still characterizes the returned view (confirmed-only, expired-flagged, hashes plus metadata, no content). For a tool with three optional params and eventual-consistency behavior, nothing an agent needs 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?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames the result set as a page-oriented chain view where `offset` follows `next_offset`, and reinforces the `github_id` omission semantics as a signed-in fallback rather than an error case.
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 and resource (list every record under one GitHub id), names the exact naming scheme it returns (`ai:gh:<id>` and `ai:gh:<id>:mem:<hash>`), and orders results (newest first). It also distinguishes itself from `read_record` by explaining that this is where the hashes needed by that sibling come from.
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?
Gives a concrete triggering scenario ('an agent starting a fresh session finds what it anchored before') and the exact handoff to `read_record`. It also states the condition for the optional parameter (omit `github_id` to list your own when signed in) and points at `whoami` for obtaining an id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the chain node behind this service is healthy and fully synced: its version, block height, header height, peer connections and sync state. It is an Emercoin node. Read-only, no sign-in required, no parameters.
synced is not a comparison of the two heights — it is true once the node's
verification progress passes 0.9999, so it can still be false while blocks
and headers already match. Trust that field, not the arithmetic. While it is
false, a read_record may reflect an older state of the chain; writes still
work, they simply confirm later.
Also the way to make sense of expiry: expires_in on a record is denominated
in blocks, and this tool reports the current height, so the two together are
the only authoritative answer to when something lapses. A term is bought in
days and charged at a flat 175 blocks each; the chain has been producing about
171 a day lately (8.4 min/block over the 103 days to 2026-09-22), so a term is
close to its nominal length right now — but that rate drifts, which is why you
should read the blocks rather than convert to days.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| blocks | No | |
| synced | No | |
| headers | No | |
| version | No | |
| connections | No | |
| verificationprogress | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, but the description adds real substance: no sign-in, the counterintuitive `synced` semantics (driven by verification progress, not height equality), and the fact that reads may lag while writes still succeed. It stops short of describing response shape or node-failure behavior, but that is largely covered by the output 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?
Purpose and the key `synced` caveat are front-loaded well, but the final paragraph spends several sentences on block-rate arithmetic (175 blocks, 8.4 min/block, 103 days to 2026-09-22) that is background trivia for a tool that simply returns heights. The core advice — read blocks, don't convert to days — could be one sentence.
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 an output schema present and no parameters, the description covers everything an agent needs: what is reported, that no auth or args are required, and how to interpret the one ambiguous field. Nothing material is missing for correct invocation.
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 parameters, so the baseline is 4; the description correctly states 'no parameters', confirming the agent needs to supply nothing.
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 and resource — check the chain node's health and sync state — and enumerates exactly what is returned (version, block height, header height, peers, sync state). An agent can immediately tell this apart from the record-oriented siblings like list_records and read_record.
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 frames usage: call it to judge whether read_record results may be stale while `synced` is false, and to combine with a record's `expires_in` (denominated in blocks) to answer expiry questions. It also warns against converting to days instead of reading block height, which is an explicit when-to / when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one on-chain record by its full name — an
agent's identity (ai:gh:<github_id>) or a memory
(ai:gh:<github_id>:mem:<hash>) written by register_identity / store_memory.
Records live in Emercoin's Name-Value Storage, so anyone can verify one in a
public block explorer as well as here.
Returns the confirmed on-chain record, or a pending one still in the mempool —
the status field ('confirmed' | 'pending') distinguishes them. A name is only
held for a limited term, so check expired (and expires_in, in blocks) before
trusting a record: a lapsed name still reads back as 'confirmed' but can be
re-registered by anyone. Read-only, no sign-in required; use whoami to find
your own github_id. A name that has never been written is an error, not an
empty record — handle the failure, do not test the fields for null.
name is the full NVS name and is capped at 512 bytes by the chain.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Full NVS record name to read. Identity records are 'ai:gh:<github_id>' (e.g. 'ai:gh:3772563'); memory records are 'ai:gh:<github_id>:mem:<sha256-hex>'. Any existing NVS name works. |
| Name | Required | Description |
|---|---|---|
| name | No | |
| time | No | |
| txid | No | |
| value | No | |
| status | No | |
| address | No | |
| expired | No | |
| pending | No | |
| operation | No | |
| days_added | No | |
| expires_at | No | |
| expires_in | No | |
| pending_update | No | |
| address_is_mine | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses important behavior: records may be `confirmed` or `pending`, expired names still read back as confirmed but can be re-registered, no sign-in is required, and missing names are errors. These are exactly the operational traits an agent needs before trusting or invoking the tool.
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 information-dense and front-loaded: it defines the resource, gives name formats, explains return status and expiration semantics, then closes with error-handling guidance. Every sentence contributes operational value.
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 single required parameter, existing output schema, and rich annotations, the description is complete enough for correct invocation. It explains the important return fields (`status`, `expired`, `expires_in`) and the key failure mode without redundantly documenting the whole output schema.
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 coverage is already 100%, so the schema carries the main parameter documentation. The description still adds useful meaning by emphasizing that `name` is the full NVS name, capped at 512 bytes by the chain, and by clarifying the identity versus memory naming forms.
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 and resource: read one on-chain NVS record by full name. It clearly distinguishes identity records from memory records and names the sibling tools that create them (`register_identity` / `store_memory`).
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?
It gives clear usage context: read one record by full name, use `whoami` to find your github_id, and treat a never-written name as an error rather than an empty record. It does not explicitly route listing/unknown-name cases to `list_records`, so it falls short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or rotate your on-chain identity record ai:gh:<github_id>, binding an
Emercoin address to your GitHub identity. Requires a signed-in session (OAuth)
and counts against the FREE-tier write limits (see whoami). Run whoami first to
confirm you are signed in; anchor memories under this identity afterwards with
store_memory. Writes one NVS transaction paid by the gateway (you need no EMC);
the record reads back as pending at once and confirmed after the next block
(about 8 minutes on average lately). Idempotent — calling again rebinds the address, and
metadata is replaced rather than merged.
Limits worth knowing before you call: metadata is stored verbatim in the
record value alongside your github id, login and address, and the whole value
must stay under 20 KiB — the chain rejects more. Every 128 bytes of name plus
value adds about 0.0001 EMC to the fee the gateway pays for you. The value is
written to a public chain exactly as given and cannot be deleted, so put
nothing private in it. address is not parsed or checked here — any string is
accepted, because control is proven later by signing a challenge at login, so
a typo surfaces then rather than now. Returns the record name and the
transaction id.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Emercoin address to bind to your GitHub identity, e.g. 'EVfAn...'. It is the anchor for later signature login — you must control its key (control is proven when you sign a challenge at login, not here). | |
| metadata | No | Optional JSON object stored verbatim in the identity record, e.g. {"agent": "my-bot", "url": "https://..."}. Omit if unused. |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| txid | Yes | |
| quota | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: gateway-paid NVS transaction (no EMC needed), `pending` immediately then `confirmed` after ~8 minutes, idempotent rebinding with `metadata` replaced rather than merged, 20 KiB chain limit, per-128-byte fee scaling, and permanent public immutability. Minor gap: it does not say what happens to a previously bound address's prior record beyond 'rebinds', though the replacement semantics are clear.
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?
Purpose is front-loaded in the first sentence and each paragraph covers a distinct concern (prerequisites, chain economics, limits). Slightly over-long, with mild redundancy — 'stored verbatim' and the public-chain immutability warning are restated in the second paragraph, and the address-validation caveat also appears in the 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?
For a two-parameter write tool with an output schema, the description covers everything an agent needs: auth prerequisite, cost/limits, timing of confirmation, idempotency, replacement semantics, and irreversibility. Return values are documented in the output schema, and the description still names what comes back (record name and tx id).
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 coverage is already 100%, yet the description still adds value: `address` is deliberately not parsed or validated so typos surface only at login, and `metadata` is stored verbatim, replaced not merged, subject to a 20 KiB cap, and publicly immutable. These are semantics the schema fields do not convey.
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 ('Create or rotate your on-chain identity record `ai:gh:<github_id>`') and states the binding operation precisely, including the record naming convention. It also routes memory storage to `store_memory` and session checks to `whoami`, so an agent can distinguish it from siblings without opening a 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?
Explicit prerequisites are given ('Requires a signed-in session (OAuth)', 'Run `whoami` first to confirm you are signed in'), along with the consequence ('counts against the FREE-tier write limits'), the follow-up action ('anchor memories under this identity afterwards with `store_memory`'), and the repeat-call behavior ('calling again rebinds the address'). Very little is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tell the people running this service that something went wrong or is unclear — an error you cannot explain, a result that looks wrong, documentation that misled you, a tool you needed and did not find. Open to everyone; no sign-in. Up to 1000 characters, a few messages per day. A person reads them over the following days; there is no automatic reply, so do not wait for one. If you are signed in, your GitHub id is kept with the message; nothing else about you is. Every refusal from this service points here.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | The tool the message is about, e.g. 'read_record'. | |
| message | Yes | Up to 1000 characters: what you tried, what came back, what you expected. No secrets — a person reads this. | |
| error_code | No | The `error` code you received, if this is about one, e.g. 'not_found'. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| note | Yes | |
| received | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Substantially exceeds the annotations: no sign-in required, rate limit of 'a few messages per day', 1000-character cap, human review over following days with no automatic reply, and a precise privacy statement (GitHub id retained only if signed in, nothing else). The 'do not wait for one' note is exactly the kind of expectation-setting an agent needs before calling a fire-and-forget write.
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?
Purpose is front-loaded in the first clause, with limits, latency, privacy, and routing following in a sensible order. The em-dash list is denser than necessary and could be trimmed, but every sentence supplies information an agent would otherwise have to guess.
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?
Output schema exists, so return values need not be explained; the description instead covers the things structured fields cannot: anonymous access, throttling, human-only handling, expected delay, and data retention. Nothing material is missing for correct invocation.
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 `tool`, `message`, and `error_code` fields are already fully documented with examples. The description echoes the 1000-character limit and reinforces privacy ('nothing else about you is'), but adds no syntax or selection guidance for the parameters beyond what the schema carries; baseline 3 applies.
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?
Opens with a specific verb and audience: telling the people running the service that something went wrong or is unclear, then enumerates the concrete cases (unexplained error, wrong result, misleading docs, missing tool). No sibling tool does anything similar, so an agent can route here without opening a 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?
Gives clear trigger conditions — unexplainable errors, suspicious results, misleading docs, absent tools — and notes that 'every refusal from this service points here', which is an explicit inbound routing rule. It stops short of naming exclusions or alternative siblings (e.g., use node_status for status checks instead), so it is clear context rather than a full when/when-not decision table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Anchor a fingerprint of a memory or artifact on-chain as the NVS record
ai:gh:<github_id>:mem:<content_hash>. Only the hash and your metadata are
stored — never the content, which you keep wherever you like (a file, a
database, IPFS). What you get is a tamper-evident, timestamped proof that
content with this hash existed, which anyone can verify later; list_records
finds your earlier ones again. Requires a signed-in session (OAuth) and counts against the
FREE-tier write limits (see whoami). Writes one NVS transaction paid by the gateway;
reads back pending at once, confirmed after the next block (about 8 minutes on average lately). Not
idempotent — each distinct hash is a new record. Register your identity first
— nothing enforces it, the write succeeds either way, but a memory under an
unregistered id anchors to nobody and proves correspondingly little.
Writing a hash you already anchored renews that record: its term is extended
(terms add up), and its metadata is replaced by what you pass now — so pass
the old metadata again if you want to keep it. That is the only renewal there
is; a record left alone lapses after its term (see expires_in).
Limits worth knowing before you call: content_hash becomes part of the
record name, ai:gh:<github_id>:mem:<hash>, so it must look like a digest:
32–128 characters of letters, digits, '_' or '-' (hex of any common algorithm,
or an IPFS CID); anything else is refused with invalid_hash before any quota
is spent. Beyond that shape it is never verified: nothing checks that it is
the hash of anything, so a wrong digest anchors happily and proves nothing. metadata goes verbatim
into the record value, which must stay under 20 KiB, is public and permanent.
Returns the record name and the transaction id.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | No | Optional JSON object stored with the record (note, source, tags, …). Omit if unused. | |
| content_hash | Yes | Hash of the artifact/memory, e.g. a SHA-256 hex digest. It becomes the record's ':mem:<hash>' suffix; the content itself stays off-chain (e.g. IPFS) — only this fingerprint is anchored. |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| txid | Yes | |
| quota | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses immediate `pending` status, `confirmed` after ~8 minutes, one NVS transaction paid by the gateway, FREE-tier write quota consumption, and that the write is non-idempotent because each distinct hash is a new record. It also explains renewal semantics (term extension, metadata replacement) and lapse behavior, which no annotation conveys.
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?
Front-loaded with the core action and record shape, then prerequisites, then renewal, then limits — a sensible order with no filler sentences. It is on the long side and repeats the record-name pattern twice, but the repetition serves the hash-format constraint.
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?
Even with an output schema present, the description mentions the return (record name and transaction id), covers failure mode, quota cost, timing, and renewal conflict semantics. An agent has everything needed to decide whether and how to call 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?
Although schema coverage is 100%, the description adds constraints the schema lacks: hash must be 32–128 chars of letters/digits/'_'/'-' or be rejected with `invalid_hash` before quota is spent, and that the hash is never verified against real content. It also bounds `metadata` under 20 KiB and warns it is public and permanent.
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 verb and resource: anchor a fingerprint of a memory/artifact on-chain as an NVS record with an explicit naming pattern `ai:gh:<github_id>:mem:<content_hash>`. It clearly delineates what is stored (hash + metadata) versus what is not (content), which distinguishes it from `list_records` and `read_record`.
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?
Gives explicit prerequisites (signed-in OAuth session, register identity first), points to `whoami` for quota and `list_records` for retrieval, and explains the renewal condition (re-submitting an existing hash). It even flags the soft-failure case where an unregistered id still writes but proves little.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Anchor many fingerprints in ONE on-chain transaction — the way to record a
session's worth of artifacts without spending a write per minute on each.
Each item becomes ai:gh:<github_id>:mem:<content_hash>, exactly as with
store_memory: only hashes and metadata, never content. All or nothing: if
any item is refused (a malformed hash, say), nothing is written.
Requires a signed-in session. A batch of N counts as N writes against the
FREE-tier limits (10 per minute, 100 per 24 hours), so at most 10 items fit
in one call on a fresh minute; the result says how many writes are left.
One transaction id comes back for the whole batch; each name reads back
pending at once and confirmed after the next block.
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | 1–100 items, each {"content_hash": "<digest>", "metadata": {...}}; metadata is optional. Same rules as store_memory for each item. |
| Name | Required | Description |
|---|---|---|
| txid | Yes | |
| count | Yes | |
| names | Yes | |
| quota | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: all-or-nothing atomicity, signed-in session requirement, per-item naming, hash-only storage, batch consumption of FREE-tier write limits, and return semantics including transaction id and pending/confirmed status.
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 definition is front-loaded with the main purpose and then covers atomicity, auth, limits, and return status efficiently. It is slightly longer than minimal but nearly every sentence carries operational value.
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 batch mutation with authentication, rate limiting, atomicity, and asynchronous confirmation behavior, the description covers the information an agent needs to invoke it correctly. The output schema exists, but the description still appropriately explains the important return status behavior.
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 coverage is already 100%, so the schema handles the basic shape. The description still adds useful meaning by explaining that `content_hash` determines the on-chain name and that only hashes and metadata are recorded, never content.
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 and resource: anchoring many fingerprints in one on-chain transaction. It distinguishes the batch operation from the sibling `store_memory` by explaining that each item becomes the same kind of memory record but in a single transaction.
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?
It gives clear usage context: recording a session's worth of artifacts without one write per minute, and it references `store_memory` for the per-item behavior. It does not explicitly say when a caller should use single `store_memory` instead, but the batching use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand your records over from the gateway's wallet to an address you choose,
in one transaction. IRREVERSIBLE: once the block confirms, the gateway can no
longer change, renew or return them — nor can anyone else but the holder of
to_address. Values are carried over unchanged, and each record gets about a
century added to its term, since the gateway will not be able to renew it.
Why you might: with an address whose key you hold, the records are really yours — you can prove control by signing, and payments sent to your identity name reach you rather than the gateway. Changing a record afterwards needs your own Emercoin node and its fees. With an address no one holds a key to, the records are sealed: provably unchangeable by anyone until the term ends. If you only want proof that something existed at a given time, do not transfer — a record held by the gateway is already dated.
Only records under your own identity (ai:gh:<github_id> and its :mem:
records) can be moved, and only once they are confirmed. Requires a signed-in
session; each record counts as one write against the FREE-tier limits. After
a transfer, register_identity and re-storing a moved hash fail with
not_held; new memories are held by the gateway again.
Changing a record costs a network fee in EMC. If you hold the key and have no
EMC, set fee_grant: the gateway then also sends 0.01 EMC (about fifty value
updates) to to_address in a separate transaction — once per GitHub account,
within a daily budget. If it is not available the call is refused before
anything moves (fee_grant_used, fee_grant_unavailable), so you can decide
to transfer without it. Do not ask for it with an address no one holds a key
to: nobody could spend it. Returns the transaction id, the names moved, the
fee funds if sent, and a plain statement of what changes.
| Name | Required | Description | Default |
|---|---|---|---|
| names | No | Records to transfer, e.g. ["ai:gh:123", "ai:gh:123:mem:<hash>"] — only your own. Omit and set `everything` instead to move them all. | |
| fee_grant | No | Also send a small amount of EMC to `to_address` to pay network fees for changing these records later from your own node. Once per account; refused before anything moves if it is not available. | |
| everything | No | Transfer your identity and every live memory at once (up to 100). Use instead of `names`. | |
| to_address | Yes | Emercoin address that will hold the records from now on. Any valid address is accepted: one whose key you hold, or one no one holds a key to, which seals the records. | |
| irreversible | Yes | Must be true. Confirms you understand the gateway can never change, renew or return these records afterwards. |
| Name | Required | Description |
|---|---|---|
| txid | Yes | |
| after | Yes | |
| count | Yes | |
| names | Yes | |
| quota | Yes | |
| fee_grant | Yes | |
| to_address | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantial context: irreversibility details, term extension, free-tier write accounting, fee_grant once-per-account behavior with a pre-move refusal guarantee, and specific error codes (not_held, fee_grant_used, fee_grant_unavailable). This goes well beyond what the annotations convey.
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 response is front-loaded with the core action and an uppercase IRREVERSIBLE warning, followed by rationale, constraints, fee_grant behavior, and returns. Despite its length, each section supports a destructive irreversible operation and 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?
Given the complexity of a destructive transfer tool with fee grants and specific failure modes, the description covers eligibility, session requirements, write-limit accounting, fee_grant edge cases, failure paths, and return content. An output schema exists, and the description still summarizes what comes back.
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 coverage is 100%, so the baseline is 3, but the description adds meaning: it explains why irreversible must be true and the consequences, clarifies fee_grant semantics and when not to request it ('Do not ask for it with an address no one holds a key to'), and reinforces that names must be your own records with everything as an alternative.
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 states a specific verb and resource — 'Hand your records over from the gateway's wallet to an address you choose, in one transaction' — and clearly distinguishes the tool from siblings like read_record and store_memory by naming the transfer/sealing tradeoff.
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?
It explicitly says when to transfer ('with an address whose key you hold, the records are really yours') and when not to ('If you only want proof that something existed at a given time, do not transfer'), and it names an alternative (a gateway-held record is already dated). It also states preconditions: only confirmed records under your own identity, signed-in session required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the current session's identity. Read-only, no sign-in required: an
anonymous session gets {authenticated: false} with a hint (not an error),
a signed-in one gets {authenticated: true} plus the GitHub-rooted id, login
and tariff. Call it to confirm who you are before register_identity /
store_memory; an anonymous caller must sign in (GitHub OAuth) first.
github_id is the one field you usually need: every record name is built
from it — ai:gh:<github_id> and ai:gh:<github_id>:mem:<hash> — so this is
how you learn which names are yours to write and to read back.
tariff is free for every account today; it governs the write limits,
currently 10 writes per minute and 100 per trailing 24 hours per account, and
writing needs a GitHub account at least 30 days old. quota says how many
writes are left right now (and, for a young account, the date writes open);
every write returns the same figures, so plan batches with them. Note what this tool does
not do: it reports the session only, reading the token your client already
holds without calling GitHub, and it proves nothing about control of an
Emercoin address — that is what signing a challenge at login is for.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| hint | No | |
| quota | No | |
| tariff | No | |
| github_id | No | |
| github_login | No | |
| authenticated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent and closed-world, but the description adds genuinely new behavioral context: no sign-in required, an anonymous call returns {authenticated: false} with a hint rather than an error, and it reads the client's existing token without contacting GitHub. It also discloses write limits (10/min, 100/24h), the 30-day GitHub account-age requirement, and how quota is reported. Those are real additions, though the tariff/quota discussion is closer to sibling-tool (write) behavior than to identity reporting.
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?
Purpose and behavior are front-loaded in the first two sentences, and the record-naming rule for github_id comes right after. It is long for a zero-argument tool, and the tariff/quota paragraph is the least essential part and could be compressed or moved to the write tools, but no sentence is pure 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?
For a no-parameter identity probe, the description covers the anonymous and authenticated response shapes, the meaning of the key fields, prerequisites, and the limits that constrain subsequent writes. An output schema exists, yet the explanation of github_id's role in naming records still adds usable context rather than duplicating schema text.
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 and there is nothing to disambiguate. The description instead spends its space on field meanings of the response (github_id as the basis of record names, tariff, quota), which is extra value rather than missing 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?
The opening sentence states a specific verb and resource: report the current session's identity. It also implicitly separates itself from siblings by framing the result as the input you need before register_identity or store_memory, so an agent knows this is the identity-probe tool rather than a record or node tool.
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?
It gives an explicit trigger ('Call it to confirm who you are before register_identity / store_memory') and the prerequisite that an anonymous caller must complete GitHub OAuth sign-in first. It also states the exclusion — it does not prove control of an Emercoin address, which is what a login challenge signature does — so the agent knows which tool answers which question.
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.
list_records1 field changedOutput schema / descriptionAdded value: +"A page of records, newest first. Pass `next_offset` back as `offset` for\nthe next page; it is null on the last one."node_status7 fields changedOutput schema / descriptionAdded value: +"Node sync status. Fields are nullable: the node may report any of them as null."Output schema / properties / blocks / defaultRemoved value: -nullOutput schema / properties / connections / defaultRemoved value: -nullOutput schema / properties / headers / defaultRemoved value: -nullOutput schema / properties / synced / defaultRemoved value: -nullOutput schema / properties / verificationprogress / defaultRemoved value: -nullOutput schema / properties / version / defaultRemoved value: -nullread_record15 fields changedOutput schema / descriptionAdded value: +"An NVS record (confirmed from the name DB, or pending from the mempool).\nA field that does not apply is left out: a pending record omits several.\n`status` says whether the write landed; `expired` says\nwhether the name is still held — a lapsed record still reads back as\n'confirmed'."Output schema / properties / address / defaultRemoved value: -nullOutput schema / properties / address_is_mine / defaultRemoved value: -nullOutput schema / properties / days_added / defaultRemoved value: -nullOutput schema / properties / expired / defaultRemoved value: -nullOutput schema / properties / expires_at / defaultRemoved value: -nullOutput schema / properties / expires_in / defaultRemoved value: -nullOutput schema / properties / name / defaultRemoved value: -nullOutput schema / properties / operation / defaultRemoved value: -nullOutput schema / properties / pending / defaultRemoved value: -nullOutput schema / properties / pending_update / defaultRemoved value: -nullOutput schema / properties / status / defaultRemoved value: -nullOutput schema / properties / time / defaultRemoved value: -nullOutput schema / properties / txid / defaultRemoved value: -nullOutput schema / properties / value / defaultRemoved value: -nullregister_identity1 field changedOutput schema / descriptionAdded value: +"The on-chain write: the NVS name written, its transaction id, and the\nwrites this account has left afterwards."send_feedback1 field changedOutput schema / descriptionAdded value: +"Confirmation that the message was stored; nothing answers it automatically."store_memory1 field changedOutput schema / descriptionAdded value: +"The on-chain write: the NVS name written, its transaction id, and the\nwrites this account has left afterwards."store_memory_batch1 field changedOutput schema / descriptionAdded value: +"One transaction for the whole batch: its id, every name written, and the\nwrites this account has left afterwards."transfer_records1 field changedOutput schema / descriptionAdded value: +"One transaction for the whole transfer: its id, the names moved, where\nthey went, what that means from now on, the network-fee funds if asked for\n(else null), and the writes left afterwards."whoami7 fields changedOutput schema / descriptionAdded value: +"The current session's identity. `authenticated` is always present; the\nGitHub-rooted fields are present only when signed in, and `hint` only when not."Output schema / properties / authenticated / defaultRemoved value: -nullOutput schema / properties / github_id / defaultRemoved value: -nullOutput schema / properties / github_login / defaultRemoved value: -nullOutput schema / properties / hint / defaultRemoved value: -nullOutput schema / properties / quota / defaultRemoved value: -nullOutput schema / properties / tariff / defaultRemoved value: -nulltransfer_records4 fields changedInput schema / properties / fee_grantAdded value: +{
+ "default": false,
+ "description": "Also send a small amount of EMC to `to_address` to pay network fees for changing these records later from your own node. Once per account; refused before anything moves if it is not available.",
+ "title": "Fee Grant",
+ "type": "boolean"
+}Output schema / $defs / FeeGrantResultAdded value: +{
+ "description": "Network-fee funds sent with a transfer: the amount in EMC, and the id of\nthe transaction that paid it — null if it could not be sent.",
+ "properties": {
+ "amount": {
+ "title": "Amount",
+ "type": "string"
+ },
+ "txid": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Txid"
+ }
+ },
+ "required": [
+ "amount",
+ "txid"
+ ],
+ "title": "FeeGrantResult",
+ "type": "object"
+}Output schema / properties / fee_grantAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/FeeGrantResult"
+ },
+ {
+ "type": "null"
+ }
+ ]
+}Output schema / requiredPrevious value: -[
- "txid",
- "count",
- "names",
- "to_address",
- "after",
- "quota"
-]New value: +[
+ "txid",
+ "count",
+ "names",
+ "to_address",
+ "after",
+ "fee_grant",
+ "quota"
+]send_feedbacktransfer_recordslist_recordsregister_identity3 fields changedOutput schema / $defsAdded value: +{
+ "Quota": {
+ "description": "Writes this account has left on its tier. `writes_open_on` (a UTC date)\nappears only while the GitHub account is too new to write.",
+ "properties": {
+ "writes_left_this_minute": {
+ "title": "Writes Left This Minute",
+ "type": "integer"
+ },
+ "writes_left_today": {
+ "title": "Writes Left Today",
+ "type": "integer"
+ },
+ "writes_open_on": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Writes Open On"
+ }
+ },
+ "title": "Quota",
+ "type": "object"
+ }
+}Output schema / properties / quotaAdded value: +{
+ "$ref": "#/$defs/Quota"
+}Output schema / requiredPrevious value: -[
- "name",
- "txid"
-]New value: +[
+ "name",
+ "txid",
+ "quota"
+]store_memory3 fields changedOutput schema / $defsAdded value: +{
+ "Quota": {
+ "description": "Writes this account has left on its tier. `writes_open_on` (a UTC date)\nappears only while the GitHub account is too new to write.",
+ "properties": {
+ "writes_left_this_minute": {
+ "title": "Writes Left This Minute",
+ "type": "integer"
+ },
+ "writes_left_today": {
+ "title": "Writes Left Today",
+ "type": "integer"
+ },
+ "writes_open_on": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Writes Open On"
+ }
+ },
+ "title": "Quota",
+ "type": "object"
+ }
+}Output schema / properties / quotaAdded value: +{
+ "$ref": "#/$defs/Quota"
+}Output schema / requiredPrevious value: -[
- "name",
- "txid"
-]New value: +[
+ "name",
+ "txid",
+ "quota"
+]store_memory_batchwhoami2 fields changedOutput schema / $defsAdded value: +{
+ "Quota": {
+ "description": "Writes this account has left on its tier. `writes_open_on` (a UTC date)\nappears only while the GitHub account is too new to write.",
+ "properties": {
+ "writes_left_this_minute": {
+ "title": "Writes Left This Minute",
+ "type": "integer"
+ },
+ "writes_left_today": {
+ "title": "Writes Left Today",
+ "type": "integer"
+ },
+ "writes_open_on": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Writes Open On"
+ }
+ },
+ "title": "Quota",
+ "type": "object"
+ }
+}Output schema / properties / quotaAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/Quota"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}read_record3 fields changedOutput schema / properties / expiredAdded value: +{
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Expired"
+}Output schema / properties / expires_atAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Expires At"
+}Output schema / properties / expires_inAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Expires In"
+}read_record1 field changedInput schema / properties / name / descriptionPrevious value: -"Full NVS record name, e.g. 'ai:gh:<github_id>:mem:<sha256-hex>'."New value: +"Full NVS record name to read. Identity records are 'ai:gh:<github_id>' (e.g. 'ai:gh:3772563'); memory records are 'ai:gh:<github_id>:mem:<sha256-hex>'. Any existing NVS name works."register_identity2 fields changedInput schema / properties / address / descriptionPrevious value: -"Your Emercoin address to bind to your GitHub identity (the anchor for signature login)."New value: +"Emercoin address to bind to your GitHub identity, e.g. 'EVfAn...'. It is the anchor for later signature login — you must control its key (control is proven when you sign a challenge at login, not here)."Input schema / properties / metadata / descriptionPrevious value: -"Optional free-form JSON metadata to store with the identity record."New value: +"Optional JSON object stored verbatim in the identity record, e.g. {\"agent\": \"my-bot\", \"url\": \"https://...\"}. Omit if unused."store_memory2 fields changedInput schema / properties / content_hash / descriptionPrevious value: -"Content hash (e.g. SHA-256 hex) of the artifact/memory; the body itself is stored off-chain."New value: +"Hash of the artifact/memory, e.g. a SHA-256 hex digest. It becomes the record's ':mem:<hash>' suffix; the content itself stays off-chain (e.g. IPFS) — only this fingerprint is anchored."Input schema / properties / metadata / descriptionPrevious value: -"Optional free-form JSON metadata (note, source, tags, …)."New value: +"Optional JSON object stored with the record (note, source, tags, …). Omit if unused."whoami13 fields changedOutput schema / properties / authenticatedAdded value: +{
+ "default": null,
+ "title": "Authenticated",
+ "type": "boolean"
+}Output schema / properties / github_id / anyOfAdded value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / properties / github_id / defaultAdded value: +nullOutput schema / properties / github_id / typeRemoved value: -"integer"Output schema / properties / github_login / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / properties / github_login / defaultAdded value: +nullOutput schema / properties / github_login / typeRemoved value: -"string"Output schema / properties / hintAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Hint"
+}Output schema / properties / tariff / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / properties / tariff / defaultAdded value: +nullOutput schema / properties / tariff / typeRemoved value: -"string"Output schema / requiredRemoved value: -[
- "github_id",
- "github_login",
- "tariff"
-]Output schema / titlePrevious value: -"Identity"New value: +"WhoAmI"node_statusread_recordregister_identitystore_memorywhoami
Add one secure layer between your agents and this server.