A connected agent doesn’t see everything Sumvin can do. It sees a fixed set of tools, chosen for the
account holder’s own errands and identity — never budgets, card controls, or anything that isn’t the
agent’s to touch. The account holder manages those in the Sumvin app or the CLI instead.
These tools are visible before an account is connected, so a client can list them as soon as the
connector is added. Each tool declares the OAuth scope it needs, and a client uses that to ask the
person to connect their Sumvin account the first time a tool needs it. Calling a tool before then
returns a refusal that asks the client to connect the account.
Someone with no Sumvin account yet sees the same tools, but every one of them needs an account first.
Calling any of them returns a refusal that carries a sign-up link to hand to the person — see
Refusals.
Each tool is either Read (returns information, changes nothing) or Write (starts or changes
something). Most tools work for anyone with an account; a few need the account holder’s identity to
be verified first — those are marked below.
Getting started
onboarding_status
Read
Show where the account holder has got to in setting up their account: which steps are done,
which are next, and how far the key they sign with has got. Reading it changes nothing.
Each stage reads current (the one to do next), pending (still ahead), submitted (handed
in and waiting on a review), completed, or skipped (waived for this account). The identity
stage can also read retry: the reviewer asked for the ID capture again. The account holder
retakes it on the verification page they already have open, and their phone stays confirmed. If
that page is closed, call kyc_start for a fresh link.
Or the identity stage can read rejected: the reviewer has made a final decision not to verify
the account holder. Trying again won’t change it, so your agent doesn’t call kyc_start for
them. It tells them plainly that their identity couldn’t be verified and points them to Sumvin
support. recorded_at is when the decision was made, and it stays final unless a reviewer later
approves them.
Each stage also carries recorded_at: when it reached its status, in epoch milliseconds. It’s
null while the stage is open, or when no time was recorded.
While the account holder still owes a signing key, the answer carries signing_key_url: the
browser page where they create and bind that key themselves. Your agent hands it to them to
open; there’s nothing it can call to bind the key on their behalf.
Try asking your agent: “Where am I up to with Sumvin?“
kyc_start
Write
Get the link that starts identity verification, and hand it to the account holder. It’s a single
browser trip: they verify a phone number, then their identity, in one sitting. If they’re already
verified, this says so instead of handing over a link.
If the reviewer has made a final decision not to verify the account holder, the call is refused
with the code KYC-403-005 and no link is made. Starting again won’t change the decision, so your
agent tells them plainly and points them to Sumvin support instead of retrying.
Try asking your agent: “Help me get verified with Sumvin.”
Identity
sigil_show
Read
Show the account holder’s Sigil — their verified identity. Reports whether it’s been issued yet,
is being issued right now, or hasn’t started. Not having one yet is a normal answer, not a problem.
Try asking your agent: “Show me my Sigil.”
agent_identity_show
Read
Show this connection’s own identity: its registration status, and whether it’s linked to the
account holder’s Sigil yet. Answers only for the connection asking — it can’t see any other agent
the account holder has connected.
Try asking your agent: “What’s your identity under my Sigil?”
Stamped Mandates
A Stamped Mandate is a signed authorisation for what one agent may do. These tools cover the
spending kind — how much an agent may spend, and until when — because that’s what the mandate
tools support today. These tools still show their internal name, pint, in two places: it’s
the same object as a Stamped Mandate, and the rename is in progress.
mandate_request
Write · Needs verification
Ask the account holder to authorise spending, and get the link that lets them review and sign it.
This doesn’t grant anything by itself — only the account holder can sign, on their own page, and
an agent can’t do that for them. Needs a wallet and a verified identity first; if either is
missing, this says which one and where to go next.
Try asking your agent: “Set up a spending limit of $50 for groceries this week.”
mandate_status
Read
Check what the account holder decided about a mandate that was requested: still waiting, signed,
declined, or expired. There’s no notification when they decide — call this again after giving them
time to look.
Try asking your agent: “Did I approve that spending limit yet?“
mandate_verify
Read
Check a Stamped Mandate someone else has presented: what it permits, up to how much, and whether
it still stands. Use this before acting on a mandate a counterparty shows you — an identifier alone
proves nothing, and a mandate can be withdrawn at any time after it’s granted.
Try asking your agent: “Check whether this mandate is still valid before we go ahead.”
mandate_capacity_query
Read
Read what’s left to spend under the Stamped Mandate authorising an errand: its limit, what’s
settled, what’s held by spending in flight, and what remains.
Try asking your agent: “How much is left on the mandate for my grocery errand?“
pint_query
Read
List the Stamped Mandates issued to the account holder. Filter by status or by identifier.
Try asking your agent: “Show me all my active spending limits.”
pint_revoke
Write
Permanently withdraw a Stamped Mandate. This can’t be undone — anything relying on it to spend
stops being able to, immediately. Find the one to revoke with pint_query first.
Try asking your agent: “Revoke the spending limit I set up for groceries.”
Payment methods
An errand pays with the card the account holder has added. These tools let an agent check that a
card is ready and, when it isn’t, send the account holder to the page where they add one. The card
is always entered on that page, by the account holder — never in the conversation.
payment_method_query
Read
List the cards the account holder has added and whether each is ready. A card can pay for an
errand only once it shows as verified. Card numbers are never shown — only the last four digits.
Try asking your agent: “Is my card ready for purchases?“
payment_method_add
Read
Get the link to the page where the account holder adds the card their errands pay with, along
with the cards they already have. The tool changes nothing itself. A card can be added once
identity verification has finished; wait for it to show as verified before starting an errand.
Try asking your agent: “I need to add a card before you buy anything for me.”
Errands
An errand is a long-running purchase task the account holder asked their agent to make, run within a Stamped Mandate.
errand_create
Write
Start a new errand from what the account holder asked for, in their own words, with the most
they’ll spend: constraints.max_total (whole purchase) or constraints.max_price (per item),
plus constraints.currency. Without a spend limit the errand isn’t created
(spend_limit_required). Starting an errand doesn’t authorise any spending on its own: the
account holder asks, signs, and only then does Sumvin search, check the merchant, watch for
their conditions, and settle the purchase.
Try asking your agent: “Reorder my usual coffee beans.”
errand_action
Write
Act on an errand that’s already running: answer a question it’s waiting on, or cancel it.
Signing an errand isn’t available here — only the account holder can sign it, before it
searches, on their own page. A pick found within the bounds they signed is then bought without
asking them again.
Try asking your agent: “Cancel that coffee order — I changed my mind.”
errand_query
Read
Read the account holder’s errands: what they are, and where each one stands. Filter by status or
by identifier.
Try asking your agent: “What’s the status of my coffee order?“
errand_events_query
Read
Read one errand’s history: what happened, and when, oldest first.
Try asking your agent: “What’s happened so far with my coffee order?”
Account
account_query
Read
Read the account holder’s linked accounts.
Try asking your agent: “What accounts do I have linked?“
wallet_query
Read
Read the account holder’s wallets.
Try asking your agent: “Show me my wallets.”
transaction_query
Read
Read the account holder’s transactions: what they spent, where, and when.
When the agent presents a Stamped Mandate that signs transactions:read with a date range, the
results are held inside that range, whether or not the question names dates, and a date outside it
is refused. Signing in to the connector alone carries no date range. See
Limit reads to a date range.
Try asking your agent: “What have I spent this week?“
asset_query
Read
Read reference data for the currencies and assets Sumvin supports. Not scoped to the account
holder — this is general information, not a personal record.
Try asking your agent: “What currencies does Sumvin support?”
Server
server_info
Read · No account needed
Report the build identity of the Sumvin server this connection has reached. Useful for confirming
the connection is live before trying anything else.
Try asking your agent: “Are you connected to Sumvin?“
sumvin_guide
Read · No account needed
Load a Sumvin guide: what Sumvin is, how to use its tools safely, and the reference file for each
task. Pass name (sumvin-sigil, or sumvin-sigil-onboard for someone without an account yet),
and file for one of its reference files. It’s the same content a host that supports skills
installs from skill://sumvin-sigil, so a host that only calls tools still gets it.
Try asking your agent: “How do you use Sumvin?”
In the Sumvin app and CLI
These tools answer only when the account holder’s own Sumvin app or the Sumvin CLI calls the
server. A connected agent never sees them: calling one from a connector is refused, and the refusal
says to manage it in the app or the CLI instead.
allocations_query
Read
List what has been spent against an errand’s mandate, newest first, and whether each spend has
settled.
budget_query
Read
Read the account holder’s budgets, by name, type, or the kind of spending they cover.
budget_upsert
Write
Create a budget, or replace one in full.
budget_delete
Write
Delete a budget. It stops counting spending; its history is kept.
card_query
Read
Read the account holder’s cards and their current status.
card_action
Write
Freeze a card, or unfreeze it. Neither cancels the card or touches payments already made.
rule_query
Read
Read the account holder’s rules.
rule_upsert
Write
Create a rule, or replace one in full.
rule_delete
Write
Delete a rule. It stops applying from then on.
strategy_list
Read
List the strategies the account holder can enrol in.
user_strategy_query
Read
Read the strategies the account holder is enrolled in.
user_strategy_create
Write
Enrol the account holder in a strategy, after checking that whatever it needs is in place.
user_strategy_update
Write
Pause or restart an enrolment, or adjust its settings.
user_agent_task_query
Read
Read the runs queued or completed for the account holder’s strategies.
user_agent_task_manage
Write
Queue a strategy run, or cancel one that hasn’t started.
wallet_update
Write
Rename a wallet, or make it the account holder’s main one. 
