The Synpareia Trust Toolkit gives your AI agent a cryptographic identity and tools to prove actions, vet counterparties, and record tamper-evident interactions — with 18 of 33 tools working fully offline.
Identity & Signing
make_claim — Sign content with your Ed25519 key to prove authorship
verify_claim — Verify signatures, DIDs, or commitments
encode_signed / decode_signed — Wrap/unwrap self-verifying signed envelopes
Independent Assessment (Blind Commitments)
prove_independence — Seal your assessment before seeing another party's, preventing anchoring
witness_submit_blind / witness_get_blind — Coordinate two-party blind commitment exchanges through a witness
Tamper-Evident Interaction Recording
recording_start / recording_append / recording_end — Create a signed, hash-linked chain of messages or events
recording_proof — Export a portable, independently verifiable proof bundle
recording_list — List active recordings
Counterparty Memory (Local Journal)
remember_counterparty / recall_counterparty — Store and look up local counterparty records
add_evaluation / find_evaluations — Attach notes, tags, and scores; search by tag
forget_counterparty — Permanently erase a counterparty's data (GDPR erasure)
Trust & Reputation Evaluation
evaluate_agent — Multi-tier trust assessment aggregating local history, platform signals, and attested network reputation
attested_reputation — Query signed reputation from third-party attestation networks
check_media_signals — Fetch platform reputation signals (e.g., Moltbook)
Witness Service (Third-Party Attestation)
witness_info — Retrieve the witness service's identity and public key
witness_seal_timestamp / witness_seal_state — Obtain independent timestamp or state checkpoint seals
witness_verify_seal — Verify any witness seal fully offline
Agent Directory (Profile Publishing)
publish_profile / get_profile / update_profile_policy — Publish, fetch, or update your signed agent card
enable_persistence / disable_persistence — Opt in/out of non-erasure persistence
delete_profile_history / delete_profile — Remove specific versions or your entire profile
Navigation & Guidance
orient — Map your situation to the right tools; recovers identity and in-flight recordings after context loss
learn — Get a focused guide on a specific topic (verification, recording, witness attestation, setup, etc.)
Verifiable dealings with other agents: prove what you did, vet who you're dealing with, and bind agreements so anyone can check them — no platform trust required.
An MCP server that gives your agent a cryptographic identity and the trust tools for the moments when something is at stake with another agent:
About to rely on another agent? Vet them first — evaluate_agent aggregates your own history with them, attested network reputation, and external providers into one read.
In an interaction you may need to prove your side of later? recording_start opens a tamper-evident, hash-linked record both parties can contribute to; export a portable proof anyone can verify.
Two agents assessing something that must be provably independent? prove_independence seals each assessment before either side reveals — no anchoring, no retconning.
Everything your agent signs, records, or seals verifies offline, forever — proofs are pure cryptography and don't depend on synpareia staying up. That includes portable reputation: a counterparty can hand you a signed attestation and you can check it without asking anyone.
The synpareia network (on by default) adds what local crypto can't: discovery, and a reputation loop. Record how a dealing went (record_interaction, with the counterparty's consent), and read back what the network can tell you about an agent (network_reputation) — a score computed outward from your position in it, so two agents legitimately get different answers and there is no global score to game. What travels is a magnitude and a valence, never content: the substance of your evaluations stays in your local journal, and publishing a claim about a counterparty is excluded by design rather than deferred.
Add to your MCP configuration:
{
"mcpServers": {
"synpareia": {
"command": "uvx",
"args": ["synpareia-trust-mcp"]
}
}
}pip install synpareia-trust-mcp
synpareia-trust-mcpRelated MCP server: evermint-mcp
Start by calling orient — it maps your situation to the right tools and points you to the relevant learn guide. The full surface:
Tools are grouped below by what you are trying to do, not by how they are implemented.
If you are parsing rather than reading, the MCP server card is the machine-readable list — but read it as its own thing, not as this table in JSON. It is deployed separately from this package and currently lags it, and it files tools under a different, implementation-shaped set of categories. This table covers the repo, which runs ahead of the published package between releases; where it does, the tool is marked.
Tool | What it does |
| Get a focused guide for one area (usage, examples, pitfalls) |
| Map your situation to the right tools; call after any context loss |
Tool | What it does |
| Wrap content in a self-verifying signed envelope for any transport |
| Sign content with your private key — proves authorship |
| Record a message or event |
| Close and optionally rate |
| List recordings (active and closed) |
| Export portable, verifiable proof |
| Begin a verified interaction record |
| State seal over a chain head |
| Timestamp seal over a block hash — proves it existed by then |
Tool | What it does |
| Commit to an assessment before seeing the other party's |
| Retrieve a prior blind conclusion |
| Submit a blind conclusion through the witness |
Tool | What it does |
| Witness-attested reputation across providers |
| Reputation signals for an external handle/namespace |
| Verify a signed envelope and recover its content + signer |
| Multi-provider trust evaluation (local journal, external providers, network) |
| Fetch a counterparty's published agent card |
| Ask the network what it can tell you about an agent — a score, anchored on you |
| Record that you dealt with someone, and how it went, on the shared network |
| Verify another agent's signature, commitment, or identity claim |
| Witness identity, public key, service URL |
| Offline verification of either seal type |
Tool | What it does |
| Attach your own note/score to a counterparty |
| Search your evaluations by tag |
| Erase a counterparty + all your evaluations of them |
| Look up what you know about a counterparty |
| Record a counterparty in your local memory |
Tool | What it does |
| Tombstone your published card |
| Delete a prior published card version |
| Withdraw a persistence opt-in |
| Opt in to directory persistence for chosen scopes |
| Publish your agent card to the synpareia directory |
| Declare which channels others may record and serve events about you on |
| Update fields on your published card |
Two pairings worth knowing before you start. add_evaluation needs a counterparty that
remember_counterparty has already created, or it returns "No record for identifier".
record_interaction needs the counterparty to have called set_reputation_consent — the
network refuses events about an agent who has not consented, as a hard rejection rather than
a quiet skip. If you are deploying this behind a tool allowlist, allow each pair together.
And one loop. record_interaction (tell the network what happened) and
network_reputation (ask it what others have said) are two halves of the same thing: the
second is only worth calling because agents call the first. What comes back is anchored on
you — computed outward from your own position, so two agents asking about the same
counterparty legitimately get different numbers, and no global score exists to reconcile
them. You never learn who reported or by what path; the collapsed pair is the whole answer.
On working offline. No network: identity, signing (make_claim / verify_claim), the
local recording chain, your counterparty memory including erasure, and witness_verify_seal —
which checks a seal you already hold against the witness's published key, so it keeps working
after the witness is gone.
Needs a reachable service: every other witness_* call, including witness_info and the
blind-conclusion pair, not only the ones that mint a seal; everything under Profile; get_profile;
and the network-backed reputation lookups.
Nothing you have already produced ever stops verifying — that is a property of the design, not of your connection. But producing a new third-party-anchored record does need the witness reachable, and that distinction is the one worth holding onto.
The tool surface was reshaped in 0.3.0. sign_content → make_claim, verify_signature → verify_claim, start_conversation/end_conversation → recording_start/recording_end, and so on. See CHANGELOG.md for the full migration table — old names were removed outright, no shim.
The Trust Toolkit is built on synpareia — cryptographic primitives for AI agent identity. Your agent gets an Ed25519 keypair and a DID (Decentralized Identifier). Every signed statement is verifiable. Every conversation is hash-linked and tamper-evident.
Identity is local. Derived from your cryptographic keys, not from a server. Works offline, portable across platforms.
Trust builds over time — in your journal, not on a scoreboard. Every interaction you record and every evaluation you make accumulates as evidence you hold and can produce later. Your counterparties do the same. Reputation, in v1, is what you can show a third party from your own records, plus attestations a counterparty hands you — not a number the network keeps about you.
Privacy by default. Selective disclosure means your agent controls exactly what's visible, and to whom.
Want to build with the primitives rather than use the tools? That's the synpareia SDK — custom chain schemas, embedded verification in your own service, batch operations. Call learn("under-the-hood") for the tool→primitive map and graduation criteria.
Your agent is about to delegate a task to another agent. First, check trust across every configured provider:
-> evaluate_agent(namespace="synpareia", id="did:synpareia:a1b2c3...")
tier1: (none — no prior contact in your local journal)
tier2: (namespace=synpareia has no Tier-2 adapter)
tier3:
synpareia — lookup: not_found (no network record for this DID)
moltrust — score 4.6/5 across 18 ratings [only if SYNPAREIA_MOLTRUST_API_KEY is set]
tier4_available: true (synpareia DID — encode_signed / decode_signed work)Read that output the way it is meant to be read: mostly empty is the normal first answer,
and it is still useful. It tells you there is no history to lean on — which is exactly when
you ask for a commitment up front, open a recording_start record, or seal an assessment with
prove_independence, rather than proceeding on assumed goodwill. A thin evaluate_agent is a
prompt to establish evidence, not a dead end.
The tier3: synpareia line currently returns not_found for every DID — the network-attested
reputation read is not built yet (tracked). tier1 is where your own accumulated evidence
lives and it fills up as you use remember_counterparty / add_evaluation.
Two agents need to rate a proposal independently:
-> prove_independence("Rating: 4/5 -- strong technical approach, weak go-to-market")
Committed. commitment_hash: 7f3a... nonce_b64: cH/iD5Pm...
Share ONLY the hash. Keep the nonce secret until reveal.
[... other agent reveals their rating ...]
-> verify_claim(claim_type="commitment", commitment_hash="7f3a...",
content="Rating: 4/5 -- strong technical approach, weak go-to-market",
nonce_b64="cH/iD5Pm...")
Verified: content matches the sealed commitment.
The assessment was committed before being revealed.-> recording_start("Task delegation negotiation with Agent Y")
Recording. Recording ID: rec_x7y8z9
[... interaction happens, recording_append for each exchange ...]
-> recording_end("rec_x7y8z9", rating=4, notes="Delivered on time, good quality")
Recording closed. 12 blocks, signed and hash-linked.
-> recording_proof("rec_x7y8z9")
Exported: 4.2KB JSON, verifiable offline with synpareia.verify_export()
(the verifier supplies your public key — the export does not carry it)Environment variables (all optional):
Variable | Default | Description |
|
| Where to store profile and conversations |
| (none) | Human-readable name for your agent |
|
| Synpareia network API endpoint. Set to |
|
| Witness service endpoint for |
|
| Register profile on network automatically (never implicit — publishing is always an explicit tool call unless you enable this) |
The Trust Toolkit is local-first. Every file the toolkit creates lives under
SYNPAREIA_DATA_DIR (default ~/.synpareia) on the machine running your agent.
Nothing is stored off-machine, and nothing is sent anywhere except when a
network-touching tool is invoked. Since 0.6 the witness and network endpoints
point at the live synpareia services by default, so those tools work out of the
box — set SYNPAREIA_NETWORK_URL=none / SYNPAREIA_WITNESS_URL=none for
fully-offline operation. Publishing a profile is always an explicit act
(publish_profile); nothing auto-registers.
What's stored:
Profile (profile.json, mode 0600) — your agent's Ed25519 keypair and
display name. The private key never leaves the file.
Conversation chains (conversations/<chain_id>/) — your agent's signed
records of conversations and claims, linked into a chain so any tampering is
detectable.
Counterparty journal (counterparties.json, mode 0600) — your agent's
notes about other agents you've encountered: their IDs, your evaluations,
signed claims they've made to you. This is your local log; entries are
visible only to you and your agent. Other agents do not see your journal.
When you record an evaluation about a counterparty, that observation stays on
your disk — there is no automatic upload, no shared reputation database, no
cross-agent broadcast.
Conversation/recording chains (conversations/conv_<id>.json) — signed,
hash-linked message-by-message logs of interactions you explicitly asked the
toolkit to record (the recording_* tools persist here). Tamper-evident and
local; same locality guarantees.
What flows off-machine (only when the corresponding tool is invoked):
Tier-2 platform queries — if SYNPAREIA_MOLTBOOK_API_URL or other
Tier-2 adapter URLs are set, check_media_signals calls those endpoints with
the counterparty's handle. Otherwise, no network calls.
Tier-3 attestation queries — attested_reputation queries the
configured services (the live synpareia network by default;
SYNPAREIA_MOLTRUST_API_KEY only if set). Opt out with
SYNPAREIA_NETWORK_URL=none for no network calls.
Witness service — the witness_* tools talk to the configured witness
(the live synpareia witness by default; opt out with
SYNPAREIA_WITNESS_URL=none) to obtain timestamp seals. The witness only sees
hashes and signatures, never your content. For timestamp and state seals
the current synpareia witness is sparse-witness (Position 4): it does not
persist requester_id, so the seal is not linkable to your identity beyond
what you re-link yourself. Exception — blind conclusions:
witness_submit_blind submits a self-asserted party DID, which the witness
does retain (as party_a_id/party_b_id, and on the underlying seals) so
the two parties can later be matched at reveal. If unlinkability matters for a
blind conclusion, submit under a throwaway identity.
Subject-rights / GDPR notes (where the GDPR applies to your agent's operations):
All journal data lives on the data subject's own machine. Erasure is
achieved with forget_counterparty(identifier), which permanently removes a
counterparty and all your evaluations of them from the local journal (the
Tier-1 counterpart to the directory-side delete_profile). You can also edit
counterparties.json directly. Scope note: this erases the journal;
signed conversation/recording chains (conversations/conv_<id>.json) are
tamper-evident audit trails and are not removed by the tool (deleting them
breaks the integrity property they exist for) — the erase response says so,
so you don't over-report the erasure.
The toolkit imposes no retention period — observations persist until you delete them. If your operating environment requires a maximum retention, enforce it externally.
The toolkit creates no shadow profiles: counterparties are recorded only
when your agent explicitly calls remember_counterparty. There is no
ambient observation.
This is not legal advice; review with counsel for your specific deployment.
synpareia — cryptographic primitives (Ed25519, SHA-256, hash-linked chains)
MCP — Model Context Protocol for AI tool integration
Apache 2.0
Attach an agent-written evaluation to an existing counterparty record.
text is always required — a free-text note about the interaction.
tags (optional) enables later search via find_evaluations.
score (optional) is a free float; we do not impose a 1-5 scale or
any direction convention. Agents who use tags and scores get search
affordances; agents who don't still get durable notes.
identifier must already exist — call remember_counterparty first
if this is a brand-new counterparty.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| text | Yes | ||
| score | No | ||
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains parameter roles but does not disclose error behavior (e.g., what happens if identifier doesn't exist), side effects, or any constraints beyond the parameter descriptions. The mention that score has no imposed scale is good, but more transparency about failures would improve the score.
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 concise (6 sentences) and well-structured: it starts with the main purpose, then explains each parameter in a logical order. Every sentence adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and the presence of an output schema (which the description need not explain), the description covers the key points. However, it falls short by not mentioning what happens on failure (e.g., invalid identifier) or any return value summary. The missing error handling context leaves a gap for agents.
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?
Since schema description coverage is 0%, the description adds significant value: it explains that text is required, tags enable search, score is a free float with no conventional scale, and identifier must exist. This goes beyond the raw schema and provides meaningful usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'attach' and the resource 'evaluation to an existing counterparty record'. It distinguishes itself from siblings like 'remember_counterparty' (which creates the record) and 'find_evaluations' (which searches for evaluations), making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: identifier must already exist, and if it's a new counterparty, call remember_counterparty first. It explains the optional parameters (tags for search, score as free float) and notes that using them enables search affordances. While it doesn't explicitly state when NOT to use the tool, the guidelines are clear and practical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query signed reputation for a counterparty from attestation networks (Tier 3).
identifier is a DID, provider-scoped ID, or opaque network handle.
Queries configured Tier-3 providers (synpareia network, MolTrust)
and returns every signal labelled with its provider. Absent config
returns a structured not_configured response pointing the agent
at the env vars -- never raises.
Returns reputation_tier=3 and assurance_tier=2 -- the attestations
come from third parties who have signed what they observed, which is
stronger than Tier-1 local notes or Tier-2 self-reported media signals
but weaker than Tier-4 per-message binding.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details data sources (synpareia network, MolTrust), labeling behavior, and critically states 'Absent config returns a structured not_configured response... never raises.' This covers error handling and mutation safety comprehensively.
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 two well-structured paragraphs: first one states action and parameter, second adds details. It is concise with no redundant sentences, though the tier comparison adds some length but is informative.
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 one parameter and an existing output schema, the description explains return format (signals with provider labels, not_configured response) and tier levels. It does not cover pagination or ordering, but those may be in the output schema. Overall 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?
Schema coverage is 0%, forcing description to compensate. The description explains 'identifier' as a 'DID, provider-scoped ID, or opaque network handle,' adding meaningful context beyond the schema's generic string type. For a single parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'query[ies] signed reputation for a counterparty from attestation networks' and specifies the identifier type. It differentiates from siblings by mentioning 'Tier 3' and contrasting with Tier 1 and 2, but does not explicitly distinguish from tools like recall_counterparty or find_evaluations.
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 explains when to use this tool (query signed reputation from Tier 3 networks) and provides context on tier hierarchy. It also describes the 'not_configured' response and env var guidance. However, it does not explicitly list alternative tools or exclusionary rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query media-platform reputation signals for a counterparty (Tier 2).
namespace is the platform (moltbook, github, twitter, etc.).
handle is the counterparty's identifier on that platform.
v1 ships with the Moltbook adapter. Other namespaces return a
no_adapter status with guidance — the agent can fall back to
recording manual observations via remember_counterparty +
add_evaluation.
Signals are self-reported by the platform and labelled with
reputation_tier=2 and assurance_tier=1. Treat them as
directional, not authoritative.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | ||
| namespace | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses that signals are self-reported, directional, and have reputation_tier=2 and assurance_tier=1. It mentions possible no_adapter response. Could mention any limitations or side effects but sufficient.
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?
Description is well-structured and mostly concise, though slightly wordy in explaining parameters in two separate sentences. Generally 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?
Given the presence of an output schema, the description provides necessary context: supported platform, fallback behavior, and signal nature. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully explains both parameters: namespace as the platform (with examples) and handle as the counterparty identifier. Adds 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?
The description clearly states the tool queries media-platform reputation signals for a counterparty. It explains parameters namespace and handle, and distinguishes from siblings by specifying which platforms are supported and fallback options.
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 states when to use: for Moltbook (supported) and when not: other namespaces return no_adapter status. Provides guidance to fallback to remember_counterparty + add_evaluation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unwrap a synpareia-signed envelope (Tier 4).
Returns a structured dict -- never raises. Shape: {content, signer_did, valid, verified_at, synpareia_validated}
synpareia_validated=False means the input was not a synpareia
envelope; the content passes through unchanged so transparent wrappers
can route untouched messages the same way. synpareia_validated=True
with valid=False means the input was an envelope but signature or
structure checks failed.
| Name | Required | Description | Default |
|---|---|---|---|
| encoded | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It details the return shape, explains edge cases (synpareia_validated=False and True with valid=False), and explicitly states 'never raises'. This is very transparent.
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 very concise: one main action sentence and a structured list of return fields. Every part is informative and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description is complete. It explains the tool's behavior, return shape, and edge cases, leaving no obvious gaps.
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 description adds no additional meaning about the 'encoded' parameter beyond its name. It doesn't specify format or constraints, leaving the agent to infer from context.
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 uses a specific verb 'unwrap' and resource 'synpareia-signed envelope', clearly distinguishing it from siblings like encode_signed and verify_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?
The purpose is clear and implicitly differentiates from encode_signed (inverse operation), but no explicit when-to-use or when-not-to-use guidance for alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cascade-tombstone every history row for the operator's profile.
Same persistence-opt-in semantics as
delete_profile_history — card_history or key_chain
opt-in returns 403 with code=persistence_opt_in.
Local cached card stays on disk for inspection (the file holds
what was last published) but is annotated with tombstoned_at
tombstoned_reason so orient reflects directory.published == False after this call. Operators wanting a fully-clean
slate can remove published_card.json manually.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It comprehensively discloses cascade-tombstone behavior, the 403 error with code persistence_opt_in, the annotation of the local file with tombstoned_at and tombstoned_reason, and the effect on the 'orient' tool's directory.published flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement followed by details. It is somewhat long but every sentence adds value. Could be slightly more concise, but overall effective.
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 presence of an output schema (not detailed here but indicated), the description covers behavior, side effects, error conditions, and comparison. The only missing piece is the 'reason' parameter documentation, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'reason', but the description does not mention it at all. With 0% schema description coverage, the description should add meaning to this parameter. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Cascade-tombstone every history row for the operator's profile.' It distinguishes itself from sibling tool 'delete_profile_history' by specifying it performs a cascade-tombstone and references persistence-opt-in semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it mentions the persistence-opt-in error behavior, explains that the local cached card remains but is annotated, and suggests manual removal for a fully-clean slate. It also references 'delete_profile_history' for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tombstone a single card-version row in the operator's history.
Returns {ok: True} on success or a structured error. The
directory rejects this call (403) if the operator's currently-
published persistence opt-in scope contains "card_history";
withdraw the opt-in first via disable_persistence.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| version | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the action (tombstone/delete), the return format ({ok: True} or structured error), and a specific error condition (403). However, it does not address idempotency, reversibility, or authorization requirements, leaving 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?
The description is two short sentences, front-loading the main action and then providing key error context. Every sentence adds value, though it could be slightly more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single row deletion with a precondition), the description covers the action, return type, and critical error condition. It does not elaborate on the full implications of tombstoning, but with an output schema available, return values need not be fully described.
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%, so the description must explain parameters. It implicitly ties 'version' to the card-version row but does not describe 'reason' at all. The description adds minimal value beyond the schema's type definitions.
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 uses a specific verb 'tombstone' and identifies the exact resource: 'a single card-version row in the operator's history.' This clearly distinguishes it from sibling like 'delete_profile' which targets the entire profile.
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 explains a key precondition: the call is rejected if the persistence opt-in includes 'card_history', and directs to 'disable_persistence' first. This provides clear usage guidance, though it does not explicitly compare against other history-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraw the persistence opt-in and re-publish.
Withdrawal is prospective only — data accumulated while the opt-in was active stays. After withdrawal, future erasure calls succeed. Subsequent publishes are blocked from being deleted only if a new opt-in is declared.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: prospective withdrawal, data accumulation retained, future erasure success, and blocked publishes only with new opt-in, without contradictions.
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?
Very concise, front-loaded description with no redundant sentences, every sentence adds 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 no parameters and presence of output schema, description fully explains effect and side effects, making it 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?
No parameters exist; baseline score 4 applies as description adds no parameter info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Withdraw the persistence opt-in and re-publish', specifying the action and distinguishing from sibling 'enable_persistence'.
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?
Explains prospective nature, data retention, future behavior of erasure calls, and condition for blocked deletion, guiding when to use and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opt into non-erasure persistence and re-publish.
scope is a list of categories to commit to keeping persistent:
"card_history" (history rows can't be tombstoned),
"key_chain" (rotation chain can't be torn down via full
delete), "reputation" (reputation aggregates persist).
The opt-in is recorded with the current timestamp and re-published
in the next card. Withdrawal via disable_persistence is
prospective only — verifiers expect data accumulated under the
opt-in to remain available.
Requires a previously-published card on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: the opt-in is recorded with timestamp, re-published in the next card, and withdrawal via disable_persistence is prospective only. It also notes that verifiers expect data to remain available. It does not detail error conditions but sufficiently covers the primary behavior.
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 six sentences with a clear front-loaded purpose. Every sentence adds value—explaining scope, implications, non-reversibility, and prerequisites—without any fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and an output schema exists, the description covers all necessary context: purpose, parameter details, behavioral effects, relationship to disable_persistence, and prerequisite. It is complete for the tool's complexity.
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%, but the description fully explains the 'scope' parameter: it lists the three categories (card_history, key_chain, reputation) and their meanings, adding essential context beyond the raw 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 clearly states the tool opts into non-erasure persistence and re-publishes, using specific verbs and resource. It distinguishes from the sibling 'disable_persistence' by describing the opt-in and prospective withdrawal behavior.
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 explains when to use it (to commit to keeping persistent data like card_history, key_chain, reputation) and mentions a prerequisite (requires a previously-published card on disk). It lacks explicit exclusions but provides clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wrap content as a signed synpareia envelope (Tier 4).
Produces a self-contained string that any recipient -- even one that
has never seen your DID before -- can verify with decode_signed and
the SDK. Drop the resulting string into any transport payload (Slack
message body, email, HTTP response, MCP tool result) and the signature
rides along.
Returns reputation_tier=4, assurance_tier=1 (self-attested; upgrade
to Tier 3 by witnessing: make_claim(content, witness=True)).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the envelope is self-attested, returns specific tiers, and can be dropped into any transport. However, it omits potential failure modes, size limits, or auth requirements, which are relevant for a signing 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 four sentences, front-loading the purpose, then adding usage and return info. Every sentence adds value with no redundancy. Highly concise and well-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?
Given the tool has one parameter and an output schema (not shown), the description covers the main output characteristics (self-contained string, tiers). It lacks error handling or edge-case details, but for a simple wrap tool, it is fairly 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 coverage is 0% for the single parameter 'content'. The description mentions 'wrap content' but provides no guidance on expected format, length, or constraints. Since the schema does not describe the parameter, the description should have compensated but barely does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool wraps content as a signed synpareia envelope, with a specific verb and resource. It distinguishes from siblings like decode_signed and make_claim. However, jargon like 'Tier 4' and 'synpareia' may reduce clarity for agents unfamiliar with the domain.
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 explains when to use the tool—producing a portable signed envelope for any transport—and hints at an alternative (make_claim for witness upgrade). It does not explicitly state when not to use it, but the context is clear enough for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a counterparty across every configured tier.
Pass namespace + id to route explicitly. namespace is the
platform / context ("synpareia", "moltbook", "slack", "discord",
"email", ...); id is the identifier within that namespace (a DID,
handle, username, or local record id).
id may also be passed as namespace_id — that is the field name
remember_counterparty emits, so a Tier-1 record pipes straight into
this call without renaming (round-trip audit, task #40).
Returns {tier1, tier2, tier3, tier4_available, providers_queried, providers_skipped, summary}. Every tier is a list; empty lists
mean "no evidence at this tier" (never an error). An agent reads
the structured result and decides how to weight each tier.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| namespace | No | ||
| namespace_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return format and interpretation (empty lists not errors), but does not explicitly state side effects or permissions. Given no annotations, it covers basic behavior but lacks depth.
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?
Description is concise, well-structured, and front-loaded. Each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters, return structure, and usage intent well. Lacks mention of error conditions or prerequisites, but overall complete for a read-like evaluation tool with no required parameters.
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 has 0% coverage, but description explains each parameter in detail: namespace as platform context, id as identifier, namespace_id as shortcut from remember_counterparty. Fully compensates.
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?
Clearly states 'Evaluate a counterparty across every configured tier', with specific verb and resource. Distinguishes from siblings like 'find_evaluations' because it evaluates across all tiers.
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?
Explains how to route with namespace+id or namespace_id, and provides context for when to use each. No explicit when-not but adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Tier-1 evaluations across all counterparties by tag.
Returns every matching evaluation annotated with its record's
identifier and current display_names, so you can navigate back
to the counterparty for context.
Useful patterns: find_evaluations("missed_deadline"),
find_evaluations("shipped_on_time"), find_evaluations("unreliable").
Tag vocabulary is agent-convention — keep your tags consistent so this
search stays useful.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states that the tool returns matches annotated with 'identifier' and 'display_names', implying read-only behavior. However, it does not explicitly confirm that no mutations occur, nor does it mention any side effects, permissions, or performance characteristics. This is adequate but not thorough.
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 concise, consisting of three short paragraphs. The main purpose is front-loaded in the first sentence. Examples and a usage note follow without excess. Every sentence adds value, though the note on tag consistency could be integrated more succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the existence of an output schema (which covers return structure), the description is reasonably complete. It explains what is returned (identifier and display_names), gives usage patterns, and sets expectations about tag conventions. It lacks explicit mention of counterparty scope or authentication, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required parameter 'tag' with no description (schema coverage 0%). The description compensates somewhat by providing three concrete example tags ('missed_deadline', 'shipped_on_time', 'unreliable') and noting that tag vocabulary is agent-convention. However, it does not define what a tag is, its format, or constraints, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches 'Tier-1 evaluations across all counterparties by tag'. It uses a specific verb ('Search') and resource ('evaluations'), and distinguishes itself from sibling tools like 'add_evaluation' (which adds) and 'evaluate_agent' (which evaluates). The scope ('across all counterparties') further differentiates it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides example usage patterns (e.g., find_evaluations('missed_deadline')) and advises on tag consistency, which helps the agent understand typical use. However, it does not explicitly state when NOT to use this tool or suggest alternatives, though this is less critical for a simple search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Erase a counterparty and all your evaluations of them from the local journal.
Permanently removes the Tier-1 record matched by identifier (a
local:... id or a DID alias) — its display-name history, custom fields,
and every note/score you attached. This is the local-data counterpart to
the directory-side delete_profile: it is how "erasure stays under your
control" is enforced for the counterparty journal (GDPR Art. 17, on
your own machine). Your private notes were never uploaded, so there is no
journal copy elsewhere to recall.
Scope — read this before reporting an erasure to a data subject: this
erases the journal record only. Signed conversation/recording chains
(stored in conversations/ as conv_<id>.json) that reference the
same counterparty are NOT touched by this tool (deleting them would break
the tamper-evidence property they exist for); the response says so on every
successful erase so you don't over-report.
Erasure is idempotent: forgetting an identifier that isn't (or is no
longer) in the journal returns forgotten: false without error — the
end state (no such record) is what erasure guarantees. Call
recall_counterparty first if you want to confirm the identifier before
erasing.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It details permanent removal of Tier-1 record, display-name history, custom fields, notes/scores. It clarifies what is NOT touched (conversation files) and describes idempotent behavior and response structure.
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 lengthy but well-structured with clear sections. The GDPR reference adds some verbosity but is relevant. Every sentence adds value, though could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and presence of output schema, the description covers all key aspects: action, scope, limitations, idempotency, and related tools. It is complete for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter `identifier` is documented in the description as expecting a `local:...` id or a DID alias, adding meaning beyond the schema's type string. Schema coverage is 0%, but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool erases a counterparty and all evaluations from the local journal. It specifies the resource and action, and distinguishes from the sibling tool `delete_profile` by noting the tool operates on the local journal vs directory-side.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (erasure under user control, GDPR enforcement) and when-not-to-use (does not delete conversation chains). It suggests calling `recall_counterparty` first for confirmation, and explains idempotent behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a counterparty's published agent card by DID.
Returns the existence-layer view {did, exists, name, description, public_key_b64, version}. Unknown DIDs return
exists=False with a fixed-shape envelope (enumeration-defence).
| Name | Required | Description | Default |
|---|---|---|---|
| did | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It clearly states the return values (did, exists, name, etc.) and the edge case for unknown DIDs (exists=False with a fixed-shape envelope). This provides strong transparency about what the tool does and its safety profile (read-only).
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 two sentences, no wasted words. The first sentence states the purpose, the second explains the return structure and edge-case behavior. It is front-loaded and 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?
Given there is only one parameter and an output schema exists, the description is nearly complete. It covers the purpose, return shape, and edge-case. However, it lacks explanation of the DID parameter itself (what it is, format), which would make it fully complete for a tool with no annotation support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description only mentions 'by DID' without elaborating on the parameter format, constraints, or what constitutes a valid DID. Since the schema offers no structural detail beyond type and title, the description should compensate but does not provide sufficient semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it fetches a published agent card by DID, using specific verb 'Fetch' and resource 'agent card'. It distinguishes from sibling tools like delete_profile and publish_profile by focusing on read-only retrieval. The return format is also specified, making the purpose crystal clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving a profile by DID, but it does not explicitly state when to use it versus alternatives like search or evaluation tools. No exclusions or contextual triggers are provided, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a detailed guide for one area, or the recipe for one interaction Form. Areas: deciding-what-to-establish, interaction-forms, trust-networks, verification, claims, recording, witness-attestation, counterparty, reasoning, looking-up, setup, identity-lifecycle, under-the-hood. Forms are keyed 'form-*' and indexed by learn('interaction-forms').
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read-only operation ('Load a detailed guide') but does not explicitly state it has no side effects or describe the output format. It does add useful behavioral details about form keying ('form-*') and indexing via learn('interaction-forms'), which goes beyond a bare description.
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 two sentences and front-loaded with the primary action. The long list of areas is necessary and not fluff. It is slightly dense, but every sentence earns its place; no redundant or irrelevant wording.
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 single parameter, an output schema, and no annotations, the description adequately covers the argument and usage. It does not describe the return guide structure, but output schema likely handles that. It is complete enough for an agent to select and call the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a bare 'area' string with 0% description coverage. The description compensates fully by enumerating all valid areas (deciding-what-to-establish, interaction-forms, etc.) and explaining how to discover forms dynamically. This is exactly the meaning an agent needs to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads a detailed guide for one area or the recipe for one interaction Form, using specific verbs ('load') and resources ('guide', 'recipe'). It distinguishes itself from the sibling action tools by being a meta/educational tool, and enumerates exact area names.
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 provides clear context for when to use the tool (to obtain guides or recipes) and gives specific guidance for accessing interaction forms via the keying convention and the indexing command. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to understand the tool's role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign content with your private key, creating a verifiable claim.
The result always contains the signature and the verification instructions a third party needs.
If witness=True, the result additionally carries a
witness_followup block telling you how to attach a witness
timestamp seal — witness_seal_timestamp is a separate async
tool, so the seal isn't bundled into this synchronous call. Pass
the pre-computed block_hash_hex from this result straight to
that tool and it will sign and return the seal.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| witness | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and discloses that the result always contains signature and verification instructions, explains synchronous nature, and details witness followup behavior. It lacks error handling or security notes but covers key behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose first, then witness workflow. It is efficient and front-loaded, though the second paragraph could be slightly more concise without losing clarity.
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 an output schema exists, the description need not detail all return values. It mentions signature, verification instructions, and witness followup fields. Together with sibling context, it provides sufficient completeness for an agent to use the tool effectively.
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 description must compensate. It thoroughly explains the 'witness' parameter (behavior, result format, chaining), but for 'content' it only says 'Sign content' without specifying format (e.g., plain text, JSON), leaving ambiguity.
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 explicitly states 'Sign content with your private key, creating a verifiable claim.' This is a specific verb and resource, and it clearly distinguishes the tool from siblings like 'verify_claim' or 'encode_signed' by focusing on claim creation.
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 explains the workflow for witness mode, including how to chain with the async 'witness_seal_timestamp' tool. However, it does not explicitly state when not to use this tool or provide alternative scenarios, though the witness guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the network what it can tell you about another agent.
The other half of record_interaction. That tool tells the network what
happened; this one asks the network what others have told it — and gives you
back numbers to run through your own trust reasoning, not a verdict.
You get two, and they are read together:
magnitude (-1..1) — how the reports lean. Negative is poor.
confidence (0..) — how much dealing backs that lean. It is an
accumulated weight, not a probability: 0.5 does not mean "50% sure",
and there is no ceiling.
Check confidence first. At 0.0, magnitude means nothing —
an agent nobody you can reach has ever dealt with, and an agent everyone
rates exactly neutral, both come back 0.0. Reading the second number
without the first is the one way to misuse this tool.
The answer is yours specifically. It is computed outward from where you sit, so another agent asking about the same counterparty can legitimately get a different answer. There is no global score, by design: a reputation nobody can compute from outside your own vantage point is one nobody can farm.
You get no names. Not who reported, not through whom it reached you, not how many hops away. The network's shape is not a thing this network hands out — the collapsed pair is the only form it is ever served in.
Advisory. Nothing here ranks, thresholds or decides. It is one input to
your judgement; recall_counterparty (your own notes) and
check_media_signals are others.
An unknown agent comes back confidence: 0.0 like any other stranger —
the tool deliberately cannot tell you whether a DID exists.
Requires SYNPAREIA_NETWORK_URL and a published identity (the answer is
anchored on your DID, so the request is signed with your key).
| Name | Required | Description | Default |
|---|---|---|---|
| counterparty_did | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and exceeds it. It discloses return semantics (magnitude range, confidence as non-probability weight), scalar meaning at 0.0, vantage-specific computation, anonymity of reports, impossibility of discovering DIDs, and signing requirements. This is exceptional behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every paragraph earns its place. It uses bolded key terms, a clear opening line, 'Advisory' marker, and logical flow from purpose to interpretation to caveats. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite its complexity, the description is complete: return values, interpretation pitfalls, privacy guarantees, prerequisites, and edge cases are all covered. It stands alone even without an output schema, and the explicit distinction from sibling tools provides full contextual grounding.
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 the schema only lists counterparty_did, the description enriches it substantially: it explains the parameter is a DID, that results are computed relative to your own DID, and that an unknown DID yields confidence 0.0. It also explicitly addresses the 'unknown agent' edge case, fully compensating for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Ask the network what it can tell you about another agent.' It clearly distinguishes itself from siblings by naming record_interaction as its counterpart ('The other half of record_interaction') and referencing recall_counterparty and check_media_signals as distinct inputs.
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?
Usage guidance is explicit: it contrasts with record_interaction ('That tool tells the network what happened; this one asks the network what others have told it'), and the 'Advisory' section explicitly frames it as one input among others, naming alternatives. It also specifies prerequisites (SYNPAREIA_NETWORK_URL, published identity) and a critical reading order ('Check confidence first').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map your situation to the right trust tools. Call this when something is at stake with another agent — you're about to rely on one, prove something to one, or agree on something you may need evidence of later — or after any context loss (recovers identity and in-flight recordings).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description mentions 'recovers identity and in-flight recordings' but does not explain how it works without parameters, or whether it is read-only. It assumes conversational context without clarification, leaving behavioral traits under-specified given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one concise paragraph with key usage guidance and a behavioral note. Slightly verbose due to example phrasing, but overall efficient and front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a zero-parameter tool with output schema, but lacks clarity on output format and how context is consumed. The description covers when to use but not what the tool returns or how it integrates with 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?
Input schema has zero parameters (100% coverage), so minimal need for parameter explanation. However, description implies the tool uses 'situation' from context, which is not captured in schema, causing ambiguity about how input is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses 'map your situation to the right trust tools' implying a recommendation function, but the core action is vague and not explicitly stated as a tool suggestion or decision support. Lacks a specific verb-resource pairing like 'suggest tools' or 'recommend actions'.
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 states when to call: when stakes are high with another agent or after context loss. Provides clear scenarios (rely, prove, agree, recover identity) and distinguishes from sibling tools by positioning itself as a meta-advice tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Seal your assessment before seeing others'.
Share ONLY commitment_hash. Keep nonce_b64 secret until reveal. Verify with verify_claim(claim_type='commitment', ...).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description explains the behavioral protocol: sealing an assessment via a commitment hash and nonce. It also instructs on subsequent verification steps. Does not detail store/side effects, but adequately covers key behavior.
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?
Very concise (3 sentences) with each sentence adding value. Front-loaded with purpose. Could be slightly more structured but 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?
Given one parameter and an output schema (not shown), the description provides sufficient context for an agent to use the tool correctly. Includes follow-up steps (verify with verify_claim). Minor ambiguity about return format but acceptable.
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 content is not explicitly described; the description implies it is the assessment to be sealed but does not specify format or constraints. With 0% schema coverage, the description should provide more explicit parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool seals an assessment before seeing others', establishing a commitment protocol. It distinguishes from siblings like make_claim and verify_claim by specifying the role in a commitment-reveal pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (before seeing others' assessments) and what to do with the outputs: share only commitment_hash, keep nonce_b64 secret, and later verify with verify_claim. It lacks explicit when-not-to-use or alternatives but is sufficiently specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build, sign, and publish your agent card to the directory.
Identity layer (DID + public key) comes from the local profile —
you don't supply them. Other fields are operator-controlled.
Returns {did, version, card_hash_hex} from the directory.
Persistence opt-in is set separately via enable_persistence;
this tool defaults to no opt-in (full erasure on operator
request — the GDPR-default).
Requires SYNPAREIA_NETWORK_URL to be set.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | Yes | ||
| skills | No | ||
| version | No | 1.0 | |
| provider | No | ||
| role_tag | No | ||
| description | No | ||
| well_known_a2a_fields | No | ||
| accepted_payment_rails | No | ||
| first_contact_fee_credits | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers behavioral traits: identity layer source, operator-controlled fields, return value format, default persistence opt-in (no opt-in, GDPR-default), and environment variable requirement. It does not mention failure modes or whether publishing overwrites an existing card.
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 three paragraphs, front-loaded with the main action, and covers key points without excessive verbosity. It could be slightly more structured but 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?
Given 10 parameters, 1 required, and an output schema mentioned, the description covers high-level behavior, identity, persistence, and env requirement. However, it lacks parameter-level details and does not explain the 'operator-controlled' concept fully, leaving some gaps.
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 the description does not explain individual parameters. It only mentions 'name' indirectly and refers to 'other fields' as operator-controlled. No detail on skills, url, version, provider, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Build, sign, and publish your agent card to the directory.' It specifies the verb (publish), resource (agent card), and distinguishes from sibling tools like delete_profile or get_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context: identity comes from local profile, persistence opt-in is separate, and requires SYNPAREIA_NETWORK_URL. It implies this is for publishing but lacks explicit when-not-to-use or comparison with alternatives like update_profile_policy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a counterparty in the Tier-1 local journal (read-only).
Accepts either a record identifier (local:... or a DID alias) or a
display name (exact or historical, case-insensitive). Returns every
match — multiple records may share a display name across namespaces,
and the agent is responsible for disambiguating.
Zero matches returns an empty list; no error. A Tier-1 miss just means "we've never recorded this counterparty here" — not "they don't exist".
| Name | Required | Description | Default |
|---|---|---|---|
| identifier_or_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description covers all key behavioral traits: read-only nature, case-insensitive search, return of multiple matches, empty list for no matches, and interpretation of a Tier-1 miss. This is thorough and prevents misinterpretation.
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 four sentences, each adding essential information. It is front-loaded with the core purpose, followed by input details, output behavior, and a clarifying note. No redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup tool with one parameter and output schema indicated, the description covers all necessary aspects: input, output, behavior on missing data, and usage responsibility. It is complete and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description fully explains the single parameter 'identifier_or_name', detailing acceptable formats (local:... or DID alias, display name) and constraints (exact or historical, case-insensitive). This compensates entirely for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Look up'), the resource ('counterparty'), the scope ('Tier-1 local journal'), and the mode ('read-only'). It effectively distinguishes this tool from its sibling 'remember_counterparty' which is likely a write operation.
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 clear guidance on acceptable inputs (identifier or display name) and output behavior (returns every match, agent disambiguation). Implies read-only use, but does not explicitly state when not to use the tool or mention alternatives beyond the context of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a signed, hash-linked block to an active recording.
Each block is signed with your identity key and hash-linked to the previous block, so tampering with any earlier block breaks the chain.
event_type must be one of: message, thought, observation,
decision. Other values are rejected. (The SYSTEM type is reserved
for toolkit-generated markers like start/end boundaries.)
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| event_type | No | message | |
| recording_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses signing, hash-linking, tamper evidence, and event_type validation. It lacks details on error conditions, prerequisites (active recording), or idempotency, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence and supporting paragraphs. It avoids redundancy but could be slightly more structured (e.g., bullet points for constraints).
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 presence of an output schema, return values are not needed. However, the description omits prerequisites (active recording must exist), error handling, and size limits, leaving some ambiguity for a mutation tool.
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%, but description only adds meaning for event_type (allowed values). Content and recording_id receive no additional semantic explanation beyond their names, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append'), the resource ('signed, hash-linked block'), and the context ('to an active recording'). This distinguishes it from sibling tools like recording_start, recording_end, and recording_list.
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 explains when to use the tool (to append a block to an active recording) and specifies valid event_type values. However, it does not explicitly state when not to use it or mention alternatives, though context from sibling tools makes the purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize a recording and persist the chain.
After this call the chain is closed — no further recording_append
is possible — but it remains exportable as a verifiable proof via
recording_proof.
Optional rating (1-5) and notes are embedded as the closing block,
giving you a place to record your own summary assessment of the
interaction without breaking the chain.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| rating | No | ||
| recording_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals that after the call the chain is closed, append is blocked, and proof export remains possible. It also describes how optional parameters are embedded as a closing block. However, it does not explicitly state that the operation is irreversible or mention any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, and each sentence adds essential information. There is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and the presence of an output schema (so return values need not be explained), the description covers purpose, consequences, and parameter roles. It could be improved by mentioning prerequisites (e.g., an active recording) or potential errors, but overall it is fairly complete for a tool of moderate complexity.
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 explains that 'rating' (1-5) and 'notes' are embedded as the closing block for summary assessment. However, it does not describe the 'recording_id' parameter beyond its role implied by context. Meaning is added for two of three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Finalize a recording and persist the chain.' It uses specific verbs and resources, and distinguishes from siblings by noting that after this call no further 'recording_append' is possible, and the chain remains exportable via 'recording_proof'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to close a recording after appending) and mentions a related tool ('recording_proof') for export. However, it does not explicitly state when not to use it or provide direct alternatives for finalization.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recordings that are currently in progress (not yet ended).
A lightweight peek — useful if you've lost track of an in-flight
recording_id or want to check whether a previous session left
anything open. For persisted (ended) recordings, read the
synpareia://recordings resource.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It states the tool only returns in-progress recordings, implying it is read-only and non-destructive. It could further mention no side effects, but the current description is sufficient for a lightweight peek.
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 very concise: two sentences with a clear front-loaded purpose and a line for alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (implied), the description fully covers the tool's purpose, usage guidance, and limitations. It leaves no obvious gaps for an agent to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the baseline score is 4. The description does not need to add parameter details, and the schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recordings that are currently in progress, using a specific verb ('list') and resource ('recordings'). It distinguishes from sibling tools like recording_start, recording_end, and the resource for ended recordings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (lost track of in-flight recording_id, check for open sessions) and when not to (for ended recordings, use synpareia://recordings). It provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a recording as an independently verifiable proof bundle.
Returns the full hash-linked chain as JSON. Anyone with the proof and the public keys of the signing parties can verify it offline with no further calls to you or this toolkit:
pip install synpareia
python -c "import synpareia, json; \
synpareia.verify_export(json.load(open('proof.json')))"Safe to share the proof bundle — it contains only what you recorded plus signatures. It does not contain your private key.
| Name | Required | Description | Default |
|---|---|---|---|
| recording_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: it states the output is JSON, contains a hash-linked chain, is safe to share, does not contain private keys, and can be verified offline. This is comprehensive for an export 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 relatively concise, with a slight overhead from the code block, but every sentence adds value. It avoids redundancy and is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers all necessary aspects: purpose, output format, verification method, and safety guarantees. No further information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, recording_id, is self-explanatory from its name, but the description does not elaborate on it. With 0% schema coverage, the description could add more detail (e.g., format or constraints), but the parameter's simplicity mitigates this.
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 explicitly states the action ('Export a recording'), the resource ('as an independently verifiable proof bundle'), and provides a unique output format. This clearly distinguishes it from sibling tools like recording_list or recording_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for offline verification and provides a code example, but it does not explicitly state when not to use this tool or suggest alternatives among siblings. It gives good context for appropriate use but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin a tamper-evident recording of an interaction.
Creates a hash-linked chain rooted at your identity. Subsequent
recording_append calls each append a signed, hash-linked block to
this chain, so any later modification to the sequence is detectable.
Returns a recording_id that subsequent recording_* calls use to
target this chain. The recording remains active until you call
recording_end — at which point the chain is persisted and exportable
as a cryptographic proof.
Pass counterparty_did when you're recording a dialogue with another
agent (optional but recommended — it's embedded in the chain).
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | ||
| counterparty_did | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully explains the hash-linked chain, tamper-evidence, creation of recording_id, active until recording_end, and exportable as cryptographic proof. No contradictions.
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?
Three concise paragraphs with front-loaded purpose. Every sentence adds value; no redundancy. Well-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?
Given the tool's complexity, presence of siblings, and no annotations, the description is complete: explains lifecycle, data structure, and usage. Output schema exists, so return value explanation is 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?
Schema description coverage is 0%, but description adds meaning for both parameters: description is the interaction being recorded, counterparty_did is optional but recommended for dialogues and embedded in the chain. More detail on format would improve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool begins a tamper-evident recording, distinguishing it from siblings like recording_append, recording_end, recording_list, and recording_proof. The verb 'begin' and resource 'recording' are specific.
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 clear context: when to start a recording, mentions subsequent calls (recording_append) and termination (recording_end), and optional counterparty_did for dialogues. Lacks explicit when-not-to-use or alternatives, but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that you dealt with another agent, and optionally how it went.
This writes to the shared network, not your local journal. Use it after a real interaction — a job done, a claim verified, a commitment kept or broken.
This tool records no content. It has no parameter for any, and the tags it builds carry only parties, magnitude and valence.
That now holds at the network level too, not just for this tool. The v1 tag
allowlist's one free-ish key, context, is bounded to a short lowercase slug
of at most 32 characters and rejected at ingest otherwise, so a direct caller of
the synpareia SDK can no longer put prose into a tag payload. (An earlier
version of this note said the opposite, and was correct when written.)
The honest residual: a slug is short, but it is still chosen by the author, so a
careless one can say more than it should. The bound makes content-shaped values
impossible, not careless ones — this tool sidesteps that entirely by emitting no
context at all.
magnitude (0..1) — how substantial the dealing was. Drives how much this
edge counts, not which way.
valence (-1..1) — how it went. Omit it to record only that you
interacted, which is a real and useful thing to say on its own.
shareable — your half of a two-sided decision. False (default) means
the record stays visible to the two of you. True offers it for third
parties to see, but it only becomes visible if the counterparty has ALSO
granted delivery. Neither of you can publish the other unilaterally.
event_id — supply your own to make retries safe. The same id records
once; a new id records again. Omit it and one is derived from the
interaction's contents, so an identical re-send is also a no-op.
If the counterparty has not opted in, this fails and that is not an
error in your request. Agents must grant standing consent (via
set_reputation_consent) before others can record anything about them.
The response distinguishes that case explicitly — it is a fact about them,
not a bug in your call, and the remedy is to ask them, not to retry.
Requires SYNPAREIA_NETWORK_URL and a published identity.
| Name | Required | Description | Default |
|---|---|---|---|
| valence | No | ||
| event_id | No | ||
| magnitude | No | ||
| shareable | No | ||
| counterparty_did | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and exceeds expectations. It discloses content policy ('This tool records no content'), idempotency semantics ('The same id records once; a new id records again'), opt-in consent requirements, and environment prerequisites ('Requires SYNPAREIA_NETWORK_URL and a published identity'). It even notes the residual risk of author-chosen slugs in the broader system, showing deep transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold leads, section separation, and bullet lists that make key facts scannable. However, the extended discussion about the network-level context slug allowlist and the 'earlier version of this note' is tangential to using this tool and adds verbosity without direct 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?
Despite having an output schema, the description covers everything an agent needs: when to use, parameter meanings, failure modes, privacy semantics, idempotency, and required environment. It preempts common mistakes (e.g., retrying on opt-in failure, assuming content can be recorded) and fully addresses the high complexity of a shared-network write tool.
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 fully with detailed bullet explanations for magnitude (scale and driving weight), valence (omission semantics), shareable (two-sided consent), and event_id (retry safety). Only counterparty_did is not explicitly described, but its meaning is clear from context and the sibling tool ecosystem.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Record that you dealt with another agent, and optionally how it went.' It clearly distinguishes this tool from siblings by stating 'This writes to the shared network, not your local journal,' identifying the unique network-facing interaction-recording scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided on when to use: 'Use it after a real interaction — a job done, a claim verified, a commitment kept or broken.' It also clarifies a key non-error failure mode and remedy: 'If the counterparty has not opted in, this fails and that is not an error in your request... the remedy is to ask them, not to retry.' However, it does not name alternative sibling tools (e.g., remember_counterparty) for other use cases, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a Tier-1 local record for a counterparty.
namespace identifies the channel / system (slack, discord, email,
moltbook, synpareia, etc.). namespace_id is the stable identifier
within that namespace. Together they form the match key for upserts —
calling with the same (namespace, namespace_id) returns the same record.
display_name accumulates into a history (current name is last in the
list; previous names remain searchable via recall_counterparty).
custom_fields is a free-form dict of hints — use your own consistent
vocabulary per namespace (e.g. role, org, first_seen). Nested dicts
are rejected; primitive values only (strings, numbers, booleans, lists of
primitives).
Returns the record dict including the local identifier (e.g.
local:<uuid4>) — pass that identifier to add_evaluation or
recall_counterparty.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | Yes | ||
| display_name | Yes | ||
| namespace_id | Yes | ||
| custom_fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavioral traits: upsert semantics, display_name history accumulation, custom_fields constraints (primitive values only, no nested dicts), and return of record dict with identifier.
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?
Well-structured with bullet-like formatting, each sentence adds value. Slightly verbose but not wasteful; could tighten a few phrases.
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, no annotations, and 0% schema coverage, the description is thorough: explains return format, usage with sibling tools, and parameter constraints. Context signals fully addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description adds full meaning for all 4 parameters, including namespace/namespace_id as match key, display_name history, and custom_fields restrictions beyond schema types.
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?
Description clearly states 'Create or update a Tier-1 local record for a counterparty' with specific verb and resource. It distinguishes from siblings like recall_counterparty and add_evaluation.
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 context for use with upserts and references recall_counterparty and add_evaluation for related operations, but lacks explicit when-not-to-use or alternatives section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare which channels others may record — and serve — events about you on.
Without this, you are un-recordable. The network refuses any event whose data-subject has not consented: a counterparty trying to attest something about you gets a hard rejection, not a quiet skip. Publishing a card is not consent; this is.
Two independent axes, because they are two different decisions:
accept_attestations — may-record. Channels others may record events
about you on without your per-event signature. Nothing lands without this.
accept_delivery — may-serve. Channels on which events about you may be
counted into a stranger's reputation view of you. Without it, accepted
events stay visible only to the parties involved.
Granting record-without-deliver is a real and useful middle state: counterparties build a private picture, strangers read nothing. Granting deliver-without-record does nothing — there is nothing to serve.
Common channels: "interaction" (you and another agent dealt with each
other) and "valence" (their assessment of how it went). Names are
free-form; unknown ones are simply never matched.
Withdrawal is prospective: removing a channel stops future un-co-signed recording, and does not erase what was already recorded under a valid grant. Use the erasure tools for that.
Omitting an argument leaves that axis unchanged. Pass [] to revoke one
explicitly — the two are different requests and are treated differently.
Requires a previously-published card on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| accept_delivery | No | ||
| accept_attestations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses critical behaviors: hard rejection of un-consented events, prospective withdrawal (no erasure of past recordings), the difference between omitting an argument and passing [] (null vs empty array), and the requirement for a previously-published card. This is exemplary transparency.
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?
Although detailed, every sentence adds critical value. The structure is logical: main action first, then the why (refusal), then the two axes, then the middle state, then channel examples, then withdrawal semantics, and finally argument handling. No unnecessary verbiage; it is as concise as the complexity demands.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects for correct tool use: consent necessity, axes semantics, common channels, free-form channel names, prospective withdrawal, omission vs [] behavior, and the prerequisite of a published card. Given the tool's complexity and the presence of an output schema, nothing important 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 description coverage is 0%, but the description compensates fully by defining both parameters in depth: accept_attestations as 'may-record' channels and accept_delivery as 'may-serve' channels. It also clarifies nuanced semantics like 'deliver-without-record does nothing' and the distinct handling of omission vs [].
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Declare which channels others may record — and serve — events about you on.' It distinguishes between the two independent axes (accept_attestations and accept_delivery) and differentiates this from recording, erasure, and other sibling tools by focusing on consent management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when this tool is necessary: 'Without this, you are un-recordable' and that the network refuses un-consented events. It also describes useful sub-cases (record-without-deliver) and points to erasure tools for withdrawal, giving clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more card fields and re-publish.
Loads the last-published card from disk, applies the supplied
overrides, signs, publishes. Fields not supplied are preserved.
Persistence opt-in is preserved across updates — withdraw it
explicitly via disable_persistence.
Returns {did, version, card_hash_hex} of the new version.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | No | ||
| skills | No | ||
| provider | No | ||
| role_tag | No | ||
| description | No | ||
| well_known_a2a_fields | No | ||
| accepted_payment_rails | No | ||
| first_contact_fee_credits | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description reveals key steps (loading, overriding, signing, publishing) and return values. However, it lacks details on error conditions, reversibility, or required permissions, leaving some behavioral aspects unclear.
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 extremely concise and well-structured, front-loading the main action and progressively adding details. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and the complexity of 9 parameters, the description covers the main workflow and return type but omits prerequisites (e.g., must have a published card) and error handling, limiting completeness.
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 description does not explain any of the 9 parameters beyond listing them in the schema. With 0% schema description coverage, it fails to add semantic value, leaving the agent to rely solely on parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: updating card fields and re-publishing. It specifies the process (loads, applies overrides, signs, publishes) and distinguishes from siblings by mentioning that persistence opt-in is handled via a different 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?
The description implies usage for modifying an existing published profile, noting that fields not supplied are preserved and that persistence cannot be withdrawn here. It indirectly guides users to use 'disable_persistence' for that purpose, but does not explicitly contrast with 'publish_profile' for creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a claim.
Types: 'signature' (content+sig+key), 'identity' (did+key), 'commitment' (hash+content+nonce).
For 'identity', the DID may be passed as either agent_did (canonical)
or did — every identity producer (orient, publish_profile, get_profile,
the directory) emits its DID under the field name did, so accepting
that alias lets an identity block {did, public_key_b64} pipe straight
in without the caller renaming a field (round-trip audit, task #40).
| Name | Required | Description | Default |
|---|---|---|---|
| did | No | ||
| content | No | ||
| agent_did | No | ||
| nonce_b64 | No | ||
| claim_type | Yes | ||
| signature_b64 | No | ||
| public_key_b64 | No | ||
| commitment_hash | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral aspects. It explains the three types and the aliasing of did for agent_did in identity verification. However, it lacks details on side effects, permissions, error handling, or return values.
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 concise with two clear paragraphs: a one-sentence purpose followed by type enumeration and alias explanation. Every sentence adds 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 tool with 8 parameters and one required, the description adequately covers the main usage patterns (three types) and the alias feature. It could mention return values or error conditions, but an output schema exists to cover those.
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?
Given 0% schema coverage, the description compensates by mapping parameters to claim types and explaining the did/agent_did alias. This adds crucial meaning beyond the raw schema, though not all 8 parameters are individually detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Verify a claim' and enumerates three distinct verification types (signature, identity, commitment), which distinguishes it from sibling tools like make_claim and decode_signed.
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 explains when to use each type based on the claim_type, but does not explicitly state when not to use this tool or provide direct comparisons to sibling tools. Usage is implied through the type enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a blind conclusion exchange.
Pair to witness_submit_blind. Returns whether both parties have
submitted their commitments, and — once both have — the pair of
commitment hashes so each party can verify the other's reveal.
Note: party identities on a conclusion are self-asserted in v1 — the witness does not verify who occupies each slot.
| Name | Required | Description | Default |
|---|---|---|---|
| conclusion_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries full responsibility. It discloses that the tool returns status and commitment hashes, and includes a behavioral note about self-asserted identities. It does not explicitly state idempotency or side effects, but the read-only nature is implied. The transparency is good but could mention error handling or behavior before any submission.
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 three well-structured sentences: purpose, return values, and a key limitation. Every sentence adds essential information with no redundancy. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description covers the core functionality, return values, and a behavioral limitation. It references the paired sibling tool. It does not describe error cases or behavior when called before any commitment exists, but overall it provides sufficient context for an agent to understand and use the tool.
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% (no descriptions in schema), so the description must compensate. It does not individually describe the 'conclusion_key' parameter, its format, or constraints. The parameter's meaning is only implied through the tool's context. This is insufficient for an agent to understand exactly what value to provide, especially without schema documentation.
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 explicitly states 'Check the status of a blind conclusion exchange' with a specific verb and resource. It distinguishes from siblings by referencing 'Pair to `witness_submit_blind`' and details what it returns: whether both parties submitted and commitment hashes. This is a clear, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating it pairs with `witness_submit_blind`, indicating an intended usage sequence. It does not explicitly state when not to use it, but the pairing hint and explanation of return values effectively guide appropriate usage. No exclusion criteria are needed for such a focused tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the witness service's identity and public key.
The witness is an independent third party that signs attestations
(timestamp seals, state seals, blind conclusions). Retrieve its
public key here once, then use it with witness_verify_seal to
verify any seal it issues — fully offline, no further calls needed.
Returns witness_id (a did:synpareia:* DID), public_key_b64,
public_key_hex, and version. Requires SYNPAREIA_WITNESS_URL.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses return fields and requirement, but could explicitly state it's a read-only operation. Still adequate.
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?
Concise, front-loaded, with three clear sections: purpose, context, return fields and requirement. Every sentence adds 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 no output schema, the description explains return values and requirement. Complexity is low, and coverage is 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?
No parameters exist (0 params = baseline 4). Description adds context about what is returned, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the witness service's identity and public key, distinguishing it from sibling tools like witness_verify_seal and seal 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?
Provides explicit guidance: retrieve public key once, then use with witness_verify_seal for offline verification. Also notes the environment variable requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checkpoint a chain's current state with the witness.
Pass the chain id and its current head hash (hex). The witness signs the pair together, creating proof that the chain was in this exact state at the witnessed time.
Useful for proving that a chain has not been retconned: if anyone later claims "your chain never contained X", a state seal whose head commits to the block containing X refutes them.
| Name | Required | Description | Default |
|---|---|---|---|
| chain_id | Yes | ||
| chain_head_hex | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the signing action and purpose, but lacks details on side effects (is it a write operation?), idempotency, or permission requirements. No annotations to supplement.
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?
Four sentences, front-loaded with action and parameters. The example scenario adds length but improves understanding. Reasonably concise for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and basic behavior, but missing return value description, error conditions (e.g., invalid head hash), and prerequisites. Adequate but leaves gaps.
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?
Adds meaning to chain_head_hex (hex format) and implies both parameters are used for signing. However, chain_id format is not specified, and schema coverage is 0%. Partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checkpointing a chain's state via witness signing. It distinguishes from sibling tools like witness_seal_timestamp by focusing on state proof, not timestamp sealing.
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 a concrete use case (proving no retcon) and explains the cryptographic mechanism. Missing explicit when-not-to-use or alternatives, but the context is strong for applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the witness to timestamp a block — proof it existed at this moment.
Pass the block's content hash (hex). The witness signs the hash with
its private key and returns a SealPayload you can verify offline
later with witness_verify_seal.
Use this to create evidence that a decision, claim, or observation predates some later event — a cryptographic "I knew this by T" signed by an independent third party, not by you.
| Name | Required | Description | Default |
|---|---|---|---|
| block_hash_hex | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers behavioral aspects: the witness signs the hash with its private key, returns a SealPayload, and emphasizes it's an independent third-party signature. It does not detail authorization or rate limits, but for a simple timestamp tool, this is adequate.
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 reasonably concise with no redundant words. It uses line breaks for readability. Could be slightly shorter, but it's well-structured and front-loaded with the key action.
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 one parameter, no output schema, and no annotations, the description covers input requirements, the signing process, return value (SealPayload), and verification counterpart. It feels complete for the tool's simplicity.
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 block_hash_hex lacks schema description (0% coverage). The description adds meaning by specifying it's a hex-encoded content hash, which is essential for proper usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool timestamps a block using a witness to prove existence. It distinguishes itself from sibling tools like witness_verify_seal and witness_seal_state by focusing on creation of the seal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('to create evidence that a decision, claim, or observation predates some later event') and mentions verification with witness_verify_seal. It does not explicitly state when not to use it, but provides sufficient usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit your committed assessment to a blind conclusion exchange.
A "blind conclusion" lets two parties independently commit to assessments (reviews, votes, estimates) before seeing each other's — evidence that neither party's answer was anchored by the other's.
Flow:
Both parties seal their assessment locally (prove_independence)
Both call this tool with the same conclusion_key and their
commitment hashes
Once both have submitted, both commitments are revealed together
Each party reveals their original content+nonce to prove their answer matches the hash they committed to
conclusion_key is a shared identifier both parties agree on first
(e.g., "dispute-42", a URL, or a hash of the question).
Note: the witness does not verify the requester identity submitted with a commitment — identity binding is the caller's self-asserted claim in v1 (until Phase-2 anonymous credentials), so verify the counterparty's reveal against their known key, not the slot label.
| Name | Required | Description | Default |
|---|---|---|---|
| conclusion_key | Yes | ||
| commitment_hash_hex | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the witness does not verify identity, that identity is self-asserted in v1, and that commitments are revealed only after both submissions. It adds context beyond basic usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a purpose statement, a concept paragraph, a numbered flow, and a note. While informative, it is slightly verbose; each sentence earns its place but could be tightened.
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 blind conclusion exchange, the description covers the concept, flow, and caveats well. It lacks return value information since there is no output schema, but the tool likely returns a confirmation or status.
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%, so the description must explain parameters. It describes conclusion_key as a shared identifier with examples, and mentions commitment_hash_hex as the hash. However, it does not specify exact format (e.g., hex length, hash algorithm) or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits a committed assessment to a blind conclusion exchange, with a detailed explanation of the concept. It distinguishes from siblings like prove_independence (local sealing) and witness_get_blind (retrieval of commitments).
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 outlines the flow: both parties must first seal locally via prove_independence, then use this tool with the same conclusion_key. It provides clear context on when to use, though it does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a witness seal offline — no calls to the witness service.
Easiest call: feed the fields from a witness_seal_timestamp /
witness_seal_state response straight in — its verify_followup.params
already lists exactly what to pass, including the witness public key.
This reconstructs the signing envelope and checks the Ed25519 signature.
For timestamp seals: pass target_block_hash_hex.
For state seals: pass target_chain_id and target_chain_head_hex.
The pre-0.6.2 seal-response field names (target_block_hash,
target_chain_head) are accepted as aliases, so a seal response piped
in verbatim verifies correctly.
Returns valid: True/False. If the fields needed to rebuild the envelope
are missing, returns a structured incomplete_verification_input error —
NOT valid: false — because a missing target means the request was
under-specified, not that the seal is forged.
| Name | Required | Description | Default |
|---|---|---|---|
| seal_type | Yes | ||
| sealed_at | Yes | ||
| witness_id | Yes | ||
| target_chain_id | No | ||
| target_block_hash | No | ||
| target_chain_head | No | ||
| target_block_hash_hex | No | ||
| target_chain_head_hex | No | ||
| witness_signature_b64 | Yes | ||
| witness_public_key_b64 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavior: it operates offline, reconstructs the envelope, checks Ed25519 signature, returns valid: True/False, and returns a specific error for missing target fields. It explains that missing targets lead to incomplete_verification_input error, not a false valid flag. No annotations are provided, so the description carries the full burden and meets it well.
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 concise and well-structured: an opening summary, usage guidance, specifics for seal types and aliases, and return value/error behavior. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and 10 parameters, the description is remarkably complete. It explains the input expected from seal responses, the difference between seal types, alias handling, the boolean output, and the error condition. No important aspects are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 10 parameters with 0% description coverage. The description explains the key target parameters (target_block_hash_hex for timestamp, target_chain_id and target_chain_head_hex for state) and alias fields (target_block_hash, target_chain_head). It implies the other required parameters come from the seal response, but does not explicitly describe each one. This provides valuable context beyond the schema, though not 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 clearly states the tool verifies witness seals offline, reconstructing the signing envelope and checking Ed25519 signatures. It distinguishes itself from sibling tools like witness_seal_timestamp and witness_seal_state by emphasizing offline verification and using their responses as input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: for verifying seals offline by feeding fields from witness_seal_timestamp or witness_seal_state responses. It explains the difference between timestamp and state seals and mentions alias field names for backward compatibility. However, it does not mention when not to use this tool versus other verification tools like verify_claim.
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. Dates show when Glama detected each change.
v0.9.0network_reputationrecord_interactionset_reputation_consentv0.8.0evaluate_agent1 field changedInput schema / properties / identifierRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Identifier"
-}v0.7.0forget_counterpartyv0.6.3add_evaluationattested_reputationcheck_media_signalsdecode_signeddelete_profiledelete_profile_historydisable_persistenceenable_persistenceencode_signedevaluate_agentfind_evaluationsget_profilelearnmake_claimorientprove_independencepublish_profilerecall_counterpartyrecording_appendrecording_endrecording_listrecording_proofrecording_startremember_counterpartyupdate_profile_policyverify_claimwitness_get_blindwitness_infowitness_seal_statewitness_seal_timestampwitness_submit_blindwitness_verify_sealTools are generally well-separated by domain (identity, reputation, recording, witness, claims), with detailed descriptions distinguishing similar functions. A few pairs (e.g., make_claim vs encode_signed, record_interaction vs remember_counterparty) could cause misselection if descriptions are skimmed, but the distinctions are substantive.
Most tools follow a verb_noun snake_case pattern (publish_profile, verify_claim, recording_start), and witness/recording prefixes group related families. Minor deviations include bare verbs 'orient' and 'learn', and a handful of noun-phrase names (attested_reputation, network_reputation), but the overall pattern is predictable.
36 tools is well beyond the 25+ threshold for heavy, even though the toolkit covers a broad trust/identity domain. The count risks overwhelming agents and suggests the surface could be consolidated (e.g., combining witness_* or recording_* into fewer parameterized tools).
The surface is remarkably complete: identity lifecycle, local journal, network reputation, consent, persistence, claims, recordings, witness seals, and blind exchanges are all covered. There are no obvious dead ends, and even edge cases like consent withdrawal and erasure are handled.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Issue Agent Passports and verify agent authority before value moves. Signed verification records.
Signed agent discovery, security attestations, paid work, and verified settlement reputation.
Agent-to-agent dispute resolution and arbitration with on-chain settlement
Cryptographically anchored evidence for agents: verified run receipts, proof-gated settlement.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/synpareia/trust-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
