Skip to main content
A connected agent’s tool set is fixed (see MCP tools), so calling something outside it always fails the same way: the tool is refused, not silently dropped. Every refusal names which of a small number of true reasons applies, and what to do about it. This page is for an agent reading a refusal it got back — it explains what each one means and what to try next. Most refusals come back as a normal tool result, not as a connection error. Read the result’s text for the reason and the next step, rather than treating any error as the same kind of problem.

​
The three lane refusals

A connected agent’s tools come from a small, named set. A call outside that set is refused for one of three distinct reasons — the reason matters, because “hand the person this sign-up link” and “ask the account holder to open the app” are different instructions.
The name called doesn’t match anything this server serves, on any connection. Most often a typo.What to do: check the name against tools/list, which returns everything this connection can actually call. Don’t guess a corrected name and retry blind.
The tool exists and the account holder can use it, but not from a connected agent — it’s held for the Sumvin app or the CLI. No scope or credential makes it appear here.What to do: don’t retry with different arguments. Tell the account holder to do this themselves, in the app or the CLI. Call tools/list to see what this connection does serve instead.
The tool needs an account, and the person being helped doesn’t have one. Someone with no account is listed the same tools as everyone else, so this is the refusal any of them returns.What to do: the refusal carries a sign-up link — hand it to the person to open in their browser. Once they’ve signed up they can come back to the same conversation and carry on; the page they finish on also gives them a prompt to start a new conversation, if they’d rather. Don’t retry tools until they say they’ve signed up. If the refusal carries no link, it points them at the Sumvin website instead.

​
Verify first

A few tools need more than an account — they need a wallet set up, or the account holder’s identity verified, before they’ll do anything. mandate_request is the clearest example: it checks these before asking the account holder to sign anything, so an unfinished setup never wastes their time on a request that couldn’t be granted.
A Stamped Mandate is granted against a wallet, and this account doesn’t have one.What to do: tell the account holder to finish setting up their account, then ask again. Check onboarding_status for where they’ve got to.
Spending authority needs the account holder’s identity to be verified, and verification hasn’t started.What to do: call kyc_start to get the link, and ask them to complete it. Then try again.
Verification is underway but hasn’t completed yet. Nothing has gone wrong.What to do: check back with onboarding_status once the account holder says they’re done, then ask again.

​
Rate limited

Too many requests in a short window gets a refusal with a wait time attached, not one of the reasons above. See Limits for how to read it.

​
General principle

A refusal that names a true, specific reason is more useful to an agent than a bare failure — so read it before deciding what to try next. If a refusal says not to retry, don’t: retrying gets the same answer until the underlying thing (an account, a wallet, a verified identity) changes.