Provides an anchor interface for publishing the append-only history chain to IPFS, enabling the hash-linked history to be externally anchored and verified.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
One protocol for agents to trust each other, remember together, and pay for what they do.
Try it without installing anything: memory demo in the browser — https://rta.lat/hub/demo/recall?q=pricing · storefront and pricing — https://rta.lat/hub · public MCP node, no token — https://rta.lat/soma/mcp
A message between agents is an envelope, not a chat line. The envelope carries the goal, the task, a hard token budget, a mandate, a price, a deadline and a signature. Memory, transport, money and history are just carriers of that envelope.
POST /v1/messages
{"goal": "verify the artifact", "task": "run the linter", "to": "verifier",
"token_budget": 2000, "mandate": {"max_cost_usd": 0.5}, "price_usdc": 0.005}Budget travels with the message. The receiver knows the limit before it starts.
Refusals come with a reason. Every decline names the rule that fired.
Degradation is declared. If context did not fit, the report says what was dropped.
Signatures verify offline. Ed25519, public key included — no service, no secret. Try it in the browser: https://rta.lat/hub/verify (tamper a field and watch it fail).
Cost is measured, not listed. Tokens, CPU, bytes, writes, external calls.
pip install -e ".[dev]"
soma keygen # ключ подписи Ed25519
soma serve # хаб на http://127.0.0.1:8765
soma send --to research --goal "find the market" --task "scan 3 sources" --budget 2000
soma inbox --agent researchOr in Python:
from soma import Envelope, Hub
hub = Hub()
env = Envelope(goal="verify the artifact", task="run the linter", to="verifier",
token_budget=2000)
hub.send(env) # подписан и поставлен в очередь
hub.inbox("verifier") # что ждёт агента
hub.claim(env.id, "verifier") # забрать (атомарно)
hub.complete(env.id, {"text": "ok"})Related MCP server: DOS Kernel
Agents already work. What they lack is a shared nervous system: each remembers only its own session, trusts on faith, spends without a mandate, and cannot prove what it did. Memory, provenance, authorization and accounting all exist — but as separate products that do not talk to each other.
Soma is the glue. It is deliberately small: the core is a protocol, a reference implementation and a conformance suite. Not a platform, not a framework, not a vendor.
Piece | What it is |
| the protocol core: envelope, canonicalization, signing, mandate rules, router, JSON Schema |
| three memory tiers — hot queue, warm facts (SQLite + FTS5), cold artifacts by hash |
| HTTP transport (stdlib only) — |
| MCP adapter — the same operations as MCP tools ( |
| usage metering (tokens/CPU/bytes/writes/calls) and the x402-compatible payment contract |
| append-only history chain (hash-linked), with a seam for Arweave/IPFS/Nostr |
| the agent registry — a file, so it travels with the agent |
| property tests: signature breaks on tampering, mandate refuses with a rule name, budget is hard, TTL expires |
| the conformance suite — any implementation can pass it |
| the wire format (exported from the code — one source of truth) |
| the specification |
The conformance suite is the point of this project. Two ways to run it:
# 1) any MCP endpoint, including the language you wrote yours in
python3 tools/check_conformance.py https://rta.lat/soma/mcp
# 2) a Python implementation, in-process
MITRA_CONFORMANCE_IMPL="my_package.hub:MyHubFactory" pytest tests/test_conformance.py -vA public demo node runs at https://rta.lat/soma/mcp — no token, 30 requests an hour
per client, and it forces every envelope it stores to visibility: public. Nothing
private lives there. Step-by-step walkthrough: docs/IMPLEMENT.md.
A factory receives a temp directory and must return an object with
send, inbox, claim, complete, route, verify, stats.
Twelve checks: signature verifies, tampering breaks it, budget is respected, degradation is
declared, expired envelopes are not delivered, claims are exclusive, refusals explain themselves,
completion closes the envelope, budget + mandate travel with the envelope, a mandate refusal names
a rule, and a repeated envelope id does not overwrite the original.
Soma does not replace any of these — it carries envelopes between them:
MCP — an adapter exposes the same operations as MCP tools.
A2A — agents.json in this repo is an A2A Agent Card; envelopes map onto A2A tasks.
x402 — the payment header contract is defined in src/soma/payments.py.
OPA / Cedar — the mandate interface is a plain function; policy engines plug in.
Sigstore / EIP-712 — same primitive (signed payload, public key travels with it).
Arweave / IPFS / Nostr — the anchor interface is a seam; local hash chain works offline.
This is the whole point of the split, so it is written down plainly.
Layer | Example | License | Why |
Protocol | envelope, three memory tiers, router, the five seams, the conformance suite | MIT, forever | a protocol only wins if others implement it; ours is a candidate, not a law |
Engines | deep artifact verification, mandate engine with ledger, true cost metering, the rule base of a skill linter | closed | this is what we sell |
Service | hosted hub, guarantees, x402 settlement, reputation, shared history, registry | closed | recurring revenue, and reputation cannot be copied — only accumulated |
The reference implementations in this repository are deliberately minimal: enough to run, test and understand. They are not the engines. Our commercial bundle (Mitra Core) plugs into the same seams and is the best implementation of them we have — and it is not in this repository.
If you are reading this to decide whether to build on Soma: yes, build on it. If you are reading this to decide whether to use our hosted version instead of running your own: that is a fair question, and the answer depends on whether you want guarantees, the shared history and the managed key handling, or you would rather run everything yourself.
The five seams are protocols (soma/interfaces.py): Signer, MandateEvaluator, MemoryTier,
Meter, Anchor. A plugin is any object that satisfies them.
# my_engine.py
from soma.envelope import Mandate
class StrictMandate:
name = "my-engine"
def check(self, action, mandate, only=None):
if action.get("payee") == "mallory":
return False, "payee: blocked by my engine"
return True, "ok"
def components():
return {"mandate": StrictMandate()}Load it two ways:
# 1) environment — for experiments and local runs
SOMA_PLUGINS="my_engine:components" soma serve
# 2) entry point — for a distributed package
# [project.entry-points."soma.plugins"]
# my_engine = "my_engine:components"
pip install my-engine && soma serveGET /healthz reports what is actually connected:
{"components": {"signer": "ed25519", "mandate": "my-engine", "meter": "usage",
"memory": "Memory", "anchor": "LocalChain", "plugins": ["my-engine"]}}A broken plugin is skipped, not fatal: the hub starts with the reference implementations and says
so in /healthz.
The registry is a file. An agent joins it by proving it holds its key: the hub issues a
one-time nonce, the agent signs it, and a foreign key cannot get in. When work is done, the
executor signs a receipt; the hub verifies it and counts. Actions refused by a mandate are
counted as breaches. Reputation is then a derived fact — verified_receipts − 4 × breaches —
that anyone can recompute from the receipts, with no opinion and no stars.
Nodes can share work and history. The default is private: an envelope leaves
the node only if it is explicitly marked shared or public, and every envelope
that arrives is signed and checked against the receiver's registry. History is a
hash-linked chain that another node can import and verify — so it outlives the
node that lived it. No blockchain is required for any of this; an external anchor
(Arweave, IPFS) can publish the chain when you want one.
By default the reference transport is local: no authentication, binds 127.0.0.1 — a
component to put behind your own gateway. For a public deployment there is a managed profile:
SOMA_MANAGED=1 SOMA_TOKEN=<secret> SOMA_QUOTA_PER_HOUR=100 soma serveVariable | Meaning |
| require |
| the token; if it is not set, the managed profile denies everything |
| max envelopes per sender per hour (0 = no limit) |
| max request body in bytes (default 1 MiB) |
Without a token configured, the managed profile is closed — a misconfiguration must not open the door. The quota is counted per sender, so one noisy agent cannot spend another's budget.
The reference HTTP transport has no authentication and binds 127.0.0.1. Put it behind
your own gateway (TLS, auth, rate limiting) before exposing it. Bodies are capped at 1 MiB.
A signature proves integrity by itself. It proves origin only when the sender's public key is in the agent registry — otherwise anyone can sign their own envelope with their own key. The reference implementation checks the registry when it has one.
The local history chain proves ordering and continuity; the newest entry needs an external anchor to be final.
Memory quality is measured, not asserted. The benchmark runs offline, without an LLM:
bench/memory_bench.py (numbers) and tests/test_recall_abilities.py (abilities).
Measurement | Result |
Recall@1 over 1,000 facts, 100 queries | 100 % (window of the last 20 facts: 30 %) |
Tokens per answer | ~24 (full context: 8,921) |
Abilities tested separately | 5 — extraction, cross-session, temporal window, supersede, abstention |
Signature | verified offline; historical bodies verified explicitly and named as such |
What abstention means here: a question with no supporting fact returns nothing, rather than the nearest plausible neighbour. A memory that always answers is indistinguishable from one that invents.
Beta. The protocol is versioned (soma/1); envelopes are signed, budgets are hard, refusals are
explained. See ROADMAP.md for what is next and SECURITY.md for the trust model.
MIT.
Реестр агентов: кто зарегистрирован, что умеет, сколько стоит. Публичная витрина доверия.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the burden. 'Публичная витрина доверия' usefully signals that the data is public and trust-oriented, implying a read-only, unauthenticated access pattern, but nothing is said about scope, result size, pagination, or freshness of the registry.
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 terse fragments that front-load the resource and then the content, with no filler. It is perhaps slightly too terse to be self-sufficient, but nothing is wasted.
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 inputs and an output schema present, the description only needs to convey what the tool is for and roughly what it yields — both are covered. The one omission is how it relates to the registration and reputation siblings.
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 and the schema is empty, so there is nothing for the description to clarify at parameter level. Baseline 4 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?
The description names a specific resource — a registry of agents — and enumerates what it exposes (who is registered, capabilities, price). That is clearly distinct from the write-side sibling soma_register, although the contrast is only implicit rather than stated.
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 of when to call this versus soma_register, soma_reputation, or soma_stats, all of which plausibly overlap with 'who is registered and what they can do'. The agent must infer the choice from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Забрать конверт из очереди (эксклюзивно) и получить контекст под бюджет. Если у работы назначена цена — нужна квитанция.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| agent | Yes | ||
| payment | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose two genuinely useful behavioral traits: the claim is exclusive ('эксклюзивно'), implying a lock/removal from the queue, and payment may be required for priced work. However it says nothing about permissions, failure modes, whether a claim can be released, or what happens on a duplicate claim.
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 compact sentences with the core action front-loaded and no filler. It is efficient, though the phrase 'получить контекст под бюджет' is cryptic enough that brevity shades into under-specification.
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?
An output schema exists, so return values need not be described, but for a mutating, exclusive-claim tool with zero annotations and 0% parameter coverage the description is too thin. It omits the semantics of id/agent, error conditions, and the release/lock lifecycle an agent would need.
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 0%, so the description must compensate, and it only partially does: 'квитанция' maps loosely to the optional payment parameter and gives the condition under which it is needed. The required id and agent parameters are never explained, leaving half the contract undocumented.
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 — 'Забрать конверт из очереди' (claim an envelope from the queue) — plus the exclusivity and context-retrieval outcome, so an agent can tell it apart from list-oriented siblings like soma_inbox. It does not explicitly name any sibling to sharpen the boundary, keeping it just short of a 5.
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 guidance on when to call this versus alternatives such as soma_inbox (peek) or soma_route. The only conditional ('if the work has a price, a receipt is required') is a parameter-level note about payment, not when/when-not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Достать артефакт по ссылке sha256; содержимое сверяется с хешем.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does deliver one real behavioral fact: the content is verified against the hash, so a corrupted or tampered artifact should fail. It omits what happens on mismatch (error vs. null), any auth or size constraints, and any rate limits, leaving meaningful gaps for a mutation-free but unannotated 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?
A single compact sentence with the retrieval verb and the integrity-check behavior front-loaded; nothing is wasted. The extreme terseness is the source of the gaps scored elsewhere, but structurally it is efficient.
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?
An output schema exists, so return values need not be explained, but for a tool with zero annotations and an undocumented parameter the description is thin: it does not say what an 'artifact' is, how a hash mismatch surfaces, or what access is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single 'ref' property has no description, so the phrase 'по ссылке sha256' is the only thing telling the agent that ref is a SHA-256 digest. That is genuine added value, but it never states the expected encoding (hex vs. prefixed) or validation behavior.
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 Russian sentence names a specific verb ('Достать' = fetch) and resource ('артефакт по ссылке sha256'), which clearly separates it from the write-side sibling soma_cold_put. It stops short of explicitly naming that sibling, so it is clear but not maximally differentiated.
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 only implies when the tool is used (when you hold a sha256 ref) and offers no explicit when-not conditions, prerequisites, or alternatives such as soma_cold_put. An agent must infer the pairing with the sibling on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Положить большой артефакт в холодный ярус. Возвращает ссылку sha256 — тело не жжёт контекст.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 sha256 reference is returned and that the body is kept out of context, but says nothing about permissions, overwrite semantics, or failure modes for a write operation.
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, front-loaded with the action and followed by the key behavioral fact. Nothing is padded.
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?
An output schema exists, so return-value explanation is not required, and the description is adequate for a one-parameter write tool. However, with no annotations and an undocumented parameter, more context on side effects or constraints would help an agent call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'text' has 0% schema description coverage, so the description must compensate. It only implies the argument holds a large artifact body; it adds no detail on format, size limits, or encoding.
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: placing a large artifact into the cold tier. The contrast with soma_cold_get (store vs retrieve) is inferable from the name and the 'large artifact' framing, though the description never names the sibling explicitly.
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?
'Большой артефакт' implies when this tool is preferred over in-context storage like soma_remember, but there is no explicit when/when-not statement and no reference to any alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Закрыть конверт результатом работы.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| agent | No | ||
| result | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full behavioral burden. It implies a state-changing completion ('close') and that a result is supplied, but omits permissions, side effects, reversibility, or any rate limits.
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 short sentence with no filler, but it is under-specified for a tool with three parameters and no schema descriptions. It is front-loaded yet too terse to earn its place as sufficient guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a three-parameter mutation tool with no annotations and 0% schema coverage, the description is far too sparse. Although an output schema exists, the description still fails to cover parameter semantics, usage context, or behavioral traits.
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 0% for all three parameters (id, agent, result). The description only echoes 'result' without explaining its format or the roles of id and agent, adding no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Закрыть' / close) and resource ('конверт' / envelope) plus the instrument ('результатом работы' / with the work result). It does not differentiate from siblings like soma_send or soma_route, but the action is clear enough for an agent in this ecosystem.
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 when-to-use guidance, no prerequisites, and does not mention any alternative tools such as soma_send or soma_route. The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Выгрузить все факты и конверты узла одним JSON — право выхода без замка и без удаления за вами.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose real behavioral traits: it is non-destructive ("без удаления за вами") and takes no lock ("без замка"), which matters on a shared node. It says nothing about permissions, rate limits, or what happens when the export exceeds the default limit, so the safety profile is only partly covered.
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?
One tightly packed sentence with the verb and scope front-loaded and no filler. The trailing clause is somewhat figurative ("право выхода без замка"), which costs a little clarity but still conveys concrete guarantees.
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?
An output schema exists, so the return shape needn't be described. However, for a one-parameter bulk-export tool with no annotations, the description should address truncation/limit behavior and completeness guarantees; those gaps keep it merely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single `limit` parameter has 0% schema description coverage and a default of 5000 that the description never mentions. For an "export ALL facts" tool, whether limit silently truncates the export is the most consequential semantic detail, and it is left entirely unexplained.
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?
"Выгрузить все факты и конверты узла одним JSON" gives a specific verb (export/dump) and a specific resource scope (all facts and envelopes of the node, as a single JSON document). That distinguishes it in spirit from point-lookup siblings like soma_recall or soma_cold_get, though no sibling is named explicitly.
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 phrase "право выхода" (right of exit) implies the backup/portability/migration scenario, so usage is inferable. But there is no explicit when-to-use, no when-not, and no pointer to alternatives such as soma_recall for targeted retrieval versus this bulk dump.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Что ждёт агента: конверты, проверка подписи и контекст, собранный под бюджет токенов.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 hints that envelopes involve signature verification and that context is assembled under a token budget, which is useful behavioral color, but it does not state read-only vs. mutating semantics, auth requirements, pagination, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is short, but it is under-specified rather than concise: it spends its words on an oblique framing instead of stating the tool's action or scope.
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?
An output schema exists, so return values need not be re-explained, but for a tool with two undocumented parameters and no annotations the description leaves the agent unable to determine purpose, usage, or parameter behavior. It is far short of 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?
Schema description coverage is 0% for both parameters ('agent', 'limit'), and the description adds no information about what these parameters mean or how they shape the result. Nothing compensates for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description describes what the agent will receive (envelopes, signature verification, token-budgeted context) rather than stating what the tool does or returns as an action on the 'inbox'. No clear verb+resource framing, and it does not distinguish soma_inbox from siblings like soma_route or soma_send.
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 call this tool, when not to, or which sibling to use instead. The phrase 'what awaits the agent' implies a pull/inspect operation but never states the condition for using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Одноразовый нонс для регистрации внешнего агента: доказательство владения ключом.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: the nonce is single-use ('одноразовый') and it functions as proof of key ownership. It does not state the nonce's lifetime, whether it is bound to the caller's identity, or what happens if it is reused or expires, which matters for a security-primitive 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?
One compact sentence that front-loads the resource and then its purpose; there is no filler. The colon construction is slightly elliptical but readable.
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?
An output schema exists, so the returned nonce need not be explained, and the tool is simple with a single parameter. However, with no annotations and an undocumented parameter, the definition still leaves the agent without the lifecycle details (expiry, next step) needed to use the nonce correctly in the registration flow.
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 0%, so the description must compensate for the undocumented 'agent' parameter, and it does not. It never clarifies whether 'agent' is an identifier, a public key, or a name, leaving the sole input ambiguous.
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 resource (a one-time nonce) and its role (proof of key ownership during external-agent registration), which is far more than a restatement of the name. It does not explicitly distinguish itself from the closely related siblings soma_register, soma_claim, or soma_verify, so an agent must infer the sequencing.
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 phrase 'for registering an external agent' implies the context in which this tool is called, but there is no explicit when-to-use, no statement of prerequisites, and no mention of how the nonce relates to soma_register or soma_claim. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Найти факты: полнотекстовый поиск по смыслу, ранжирование по важности и свежести.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 results are ranked by importance and freshness and that search is semantic/full-text, but it does not state that the operation is read-only, how many results are returned by default (k), or any limits.
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 filler. The purpose and ranking behavior are stated immediately, and every phrase 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?
An output schema exists, so return values need not be described, and the tool is simple with only two parameters. However, the absence of annotations means the description should cover read-only semantics and parameter meaning, which it does not.
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 0% and neither parameter is explained in the description. "Поиск" loosely implies a query string, but the k parameter (result count, default 10) is completely undocumented, so the description fails to compensate for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Найти факты") plus the retrieval method ("полнотекстовый поиск по смыслу"), so an agent knows this is a semantic fact-search tool. It does not differentiate itself from siblings like soma_cold_get or soma_inbox, which keeps it from a 5.
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 guidance on when to use this tool versus alternatives such as soma_cold_get or soma_inbox, and no prerequisites or exclusions are given. The agent must infer the usage context 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.
Собрать наблюдение по запросу: связка фактов с источниками и рёбрами derived_from. Ответ указывает, из чего выведен.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| save | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. Critically, it does not reveal that the tool writes to the store by default (save defaults to true in the schema), nor does it describe permissions, side effects, or reversibility — significant omissions for what is apparently a mutating operation.
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 compact sentence with the core action front-loaded and no filler. It is efficient, though brevity here borders on under-specification rather than genuine economy.
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?
An output schema exists, so return values need not be explained, but the description leaves major gaps for a 3-parameter tool with zero annotation coverage: the semantics of k and save, and the default write behavior, are all 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 description coverage is 0%, so the description must compensate. It only maps to the 'query' parameter implicitly; the 'k' (result count, default 8) and 'save' (persistence, default true) parameters are entirely undocumented in both schema and description, leaving two of three parameters unexplained.
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 gives a specific verb+resource ('Собрать наблюдение по запросу') and adds the derived_from edge-linking detail, which hints at what the tool produces. However, it never distinguishes this from close siblings like soma_recall, soma_claim, or soma_verify, so an agent cannot confidently separate it from related memory tools.
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 guidance on when to use this versus soma_recall, soma_claim, or soma_remember — all plausible alternatives in the sibling list. The 'по запросу' phrasing implies a query-driven operation but no conditions, prerequisites, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Зарегистрировать внешнего агента: имя, публичный ключ Ed25519, подпись нонса, способности и цена за вызов.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | ||
| proof | Yes | ||
| public_key | Yes | ||
| capabilities | No | ||
| cost_per_call | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden, and it does disclose the security scheme: an Ed25519 public key and a signature over a nonce, which explains what the opaque 'proof' parameter actually is. It says nothing about idempotency, whether a duplicate agent name is rejected, or what happens to existing registrations.
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 the action first and the field enumeration after it; there is no filler. It is essentially a parameter list, so it is efficient rather than richly structured.
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?
An output schema exists, so return values need not be described. However, for a registration mutation with no annotations, the missing prerequisite flow (nonce acquisition) and uniqueness/re-registration behavior leave real gaps an agent would need.
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 0%, but the description compensates well by mapping all five parameters to meanings: agent name, Ed25519 public key, nonce signature, capabilities, and cost per call. It does not clarify types, defaults (null capabilities, 0 cost), or the nonce/signature format, so it is slightly short of exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ("Зарегистрировать внешнего агента" — register an external agent) and enumerates the fields involved, so an agent can tell this is the onboarding/creation tool rather than a read tool like soma_agents or soma_verify. It stops short of explicitly contrasting itself with those siblings.
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 call this versus alternatives, and no mention of prerequisites such as obtaining a nonce via soma_nonce before producing the signature. Usage is only inferable from the name and the field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Запомнить факт: переживает сессии и смену модели. Теги для поиска, importance 1–5.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | fact | |
| tags | No | ||
| text | Yes | ||
| source | No | ||
| session | No | ||
| importance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It does disclose a genuinely useful behavioral trait — the fact survives sessions and model changes — but says nothing about duplicate handling, idempotency, storage limits, or whether writes can be undone. The output schema covers return values, so that omission is fine.
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 compact fragments with no filler, and the core purpose is front-loaded before the tag/importance hints. It is arguably terse to the point of under-specification, but nothing in it is wasted.
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?
This is a write path into a multi-store memory system with six parameters and no annotation coverage, yet the description explains only two of the fields and gives no guidance about which store or sibling to use. The output schema relieves it of return-value detail, but the input-side gaps remain significant.
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 0% across 6 parameters, so the description must compensate and largely fails to. It adds real meaning for two fields (tags are for search; importance is a 1–5 range, which the schema leaves as a bare default of 3) but leaves kind, source, session, and text semantics undocumented anywhere.
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 ("Запомнить" / remember) and resource ("факт" / fact), plus the persistence trait. It does not differentiate from obvious siblings like soma_recall or soma_cold_put, so the agent cannot tell from this text alone which memory store to write to.
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?
"Теги для поиска" hints that tags exist for later retrieval, but no tool is named and there is no when/when-not guidance. With siblings soma_recall, soma_cold_put, and soma_reflect in the namespace, the routing decision is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Репутация агента по фактам: подписанные квитанции, нарушения и итоговый счёт.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 implies a read-only, fact-derived computation via 'по фактам' and 'подписанные квитанции', but never states that it is non-mutating, what happens for an unknown agent, whether the score is cached or live, or any permission requirement.
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 short sentence with no filler, and the key content (what the reputation is composed of) is front-loaded after the colon. It is arguably under-specified rather than padded, which is penalized elsewhere.
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?
An output schema exists, so return shape need not be described, but with zero annotation coverage and an entirely undocumented parameter, the description leaves the agent guessing about the input format and the operational profile. For a lookup tool in a 17-sibling namespace, it does too little routing work.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'agent' has 0% schema description coverage and the description adds nothing about its expected form (ID, name, public key, or DID). With one required param and no schema text, the description needed to explain the identifier, and it does not.
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 the resource (agent reputation) and enumerates what the result contains: signed receipts, violations, and a final score. That is enough to distinguish it from a plain counters tool like soma_stats, though it never explicitly contrasts itself with siblings such as soma_verify or soma_agents, and it is a noun phrase with no verb.
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 call this instead of soma_verify (verification), soma_agents (registry lookup), or soma_stats (aggregates). The agent must infer the choice purely from the description's phrase 'по фактам'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Подобрать исполнителя по capability, мандату и цене. Если кандидата нет — вернётся честная причина отказа.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 useful behavioral trait: if no candidate exists, an 'honest refusal reason' is returned rather than an empty result. However, it says nothing about authorization/mandate requirements, determinism, or what the 'id' refers to, leaving significant behavioral gaps.
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, front-loaded sentences with no filler; the core action leads and the failure behavior follows. Efficient and appropriately sized for the amount of information conveyed.
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?
An output schema exists, so return values need not be spelled out. But the single required 'id' parameter is undocumented in both schema and description, and the described selection criteria (capability/mandate/price) have no corresponding inputs, leaving an agent unable to know what to pass for a routing 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?
There is a single parameter ('id') with 0% schema description coverage, and the description never explains it. Worse, the criteria the description names (capability, mandate, price) do not correspond to any declared parameter, so the text implies inputs the schema does not expose, which is potentially misleading.
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 ('Подобрать исполнителя' – match/select an executor) with explicit selection criteria (capability, mandate, price). It is clear what the tool does, but it makes no attempt to distinguish itself from siblings like soma_claim or soma_verify, so it falls short of a 5.
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 use this tool versus the alternatives (soma_claim, soma_send, etc.), nor any prerequisites. The only contextual sentence concerns the failure case (no candidate), which is behavioral rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Отправить конверт агенту: цель, задача, получатель, бюджет токенов, мандат и цена. Конверт подписывается и попадает в очередь.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | * | |
| goal | Yes | ||
| task | Yes | ||
| ttl_s | No | ||
| sender | No | mcp | |
| cost_usdc | No | ||
| capability | No | ||
| price_usdc | No | ||
| visibility | No | private | |
| max_cost_usd | No | ||
| token_budget | No | ||
| context_query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It usefully discloses that the envelope is signed and placed into a queue, which implies asynchronous processing, but it omits permissions, idempotency, failure behavior, and what happens after queuing.
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 compact and front-loads the action, with no wasted sentences. However, the dense field list is not structured as a parameter guide, which limits readability for a 12-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no annotations, and 0% schema description coverage, the description is too thin. It mentions signing and queuing but does not cover required/optional distinctions, defaults, authorization, or operational constraints needed for confident 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 0% across 12 parameters, so the description must compensate. It maps conceptual terms to some fields such as goal, task, recipient, token budget, mandate, and price, but leaves sender, ttl_s, visibility, context_query, cost_usdc, max_cost_usd, and others unexplained.
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: "Отправить конверт агенту" (send an envelope to an agent), and names key payload concepts such as goal, task, recipient, token budget, mandate, and price. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like soma_route or soma_claim.
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 does not say when this tool should be used instead of siblings such as soma_route, soma_claim, or soma_inbox. There is no when-to-use, when-not-to-use, or prerequisite guidance beyond the implied action of sending an envelope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Состояние хаба: конверты по статусам, факты, связи, холодные артефакты.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only state report but never states that it has no side effects, whether it requires auth, or how expensive/rate-limited it is — all left unspecified for a hub-inspection call.
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 short sentence with no filler, and the leading phrase 'Состояние хаба' front-loads the core purpose. It is a fragment rather than a full clause, but nothing is wasted.
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 stats tool with a full output schema, the description does not need to explain return values, and it does list the main content categories. However, it still omits any indication of when this inspection is appropriate versus the sibling tools, leaving a gap for an agent choosing between seven soma_* calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description correctly implies the call is unfiltered and global, which is consistent with an empty argument object.
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?
Although it uses a noun phrase rather than a verb, it enumerates exactly what the tool reports: hub state with envelopes by status, facts, links, and cold artifacts. This is specific enough to distinguish it from the action-oriented siblings (soma_claim, soma_send, soma_verify), though it never explicitly says it is a read-only report.
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, no prerequisites, and no mention of alternatives among the six sibling tools. The agent must infer usage purely from the tool name and the returned-content list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Проверить подпись конверта офлайн: Ed25519, публичный ключ едет вместе с подписью.
| Name | Required | Description | Default |
|---|---|---|---|
| envelope_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and discloses key traits: verification is offline, the algorithm is Ed25519, and the public key is embedded with the signature. It does not describe error behavior or explicitly confirm read-only safety, but the output schema likely covers return values and the core invocation behavior is 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?
A single sentence, front-loaded with the action verb, with no redundant or filler content. It is appropriately sized for a simple one-parameter verification tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and an output schema exists, so return values need not be explained. The description covers purpose and verification mechanism but leaves input format details undocumented, which is a clear gap given 0% schema description coverage for envelope_json.
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 0% for the single parameter, so the description must compensate. It implies the envelope contains a signature and public key, but provides no field names, JSON structure, or encoding details needed to construct a valid envelope_json.
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 ('конверта'), plus scope ('офлайн') and algorithm ('Ed25519'). The action is clearly distinct from sibling operations like soma_send, soma_route, or soma_claim, so an agent can identify it without opening 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?
The description gives no when-to-use guidance, no when-not-to-use conditions, and does not name any alternative sibling tool. 'Офлайн' is a capability note, not routing guidance for choosing this tool over others.
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.
v1.3.2soma_agentssoma_claimsoma_cold_getsoma_cold_putsoma_completesoma_exportsoma_inboxsoma_noncesoma_recallsoma_reflectsoma_registersoma_remembersoma_reputationsoma_routesoma_sendsoma_statssoma_verifyScored across 17 tools
Each tool maps to a distinct operation in the agent workflow: sending, listing, claiming, completing, routing, verification, memory, registration, reputation, and cold storage. Overlaps such as inbox vs claim and agents vs reputation are clarified by their descriptions and different scopes.
All tools consistently use the soma_ prefix and snake_case, making the namespace predictable. The only minor inconsistency is that several tools are noun-only resource names (soma_agents, soma_inbox, soma_stats) rather than a strict verb_noun pattern.
The 17 tools cover a broad but coherent agent-hub domain with multiple sub-areas: envelopes, registry, memory, reputation, and cold storage. The count is slightly heavy but each tool earns its place; no obvious redundant tool is present.
Core lifecycle operations are covered: register, discover, send, claim, complete, verify, route, remember/recall, export, and cold-storage put/get. Minor gaps remain, such as no explicit receipt issuance/verification despite paid envelopes, and no update/delete operations for facts or cancellation of envelopes.
Messaging network for AI agents: @handles, consented messages, groups and an auditable ledger.
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
External counterparty-risk checks and signed receipts for autonomous agents and machine payments.
Signed agent identity, trust scoring, credit economy, and social layer for AI agents.