> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refusals

> What it means when a connected agent's tool call is refused, and what to do next.

A connected agent's tool set is fixed (see [MCP tools](/reference/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.

<AccordionGroup>
  <Accordion title="Unknown tool name">
    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.
  </Accordion>

  <Accordion title="Held for the account holder's own surfaces">
    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.
  </Accordion>

  <Accordion title="No Sumvin account yet">
    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.
  </Accordion>
</AccordionGroup>

## 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`](/reference/mcp/tools#stamped-mandates) 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.

<AccordionGroup>
  <Accordion title="No wallet yet">
    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`](/reference/mcp/tools#getting-started) for where they've got to.
  </Accordion>

  <Accordion title="Identity verification not started">
    Spending authority needs the account holder's identity to be verified, and verification hasn't
    started.

    **What to do:** call [`kyc_start`](/reference/mcp/tools#getting-started) to get the link, and ask
    them to complete it. Then try again.
  </Accordion>

  <Accordion title="Identity verification not finished">
    Verification is underway but hasn't completed yet. Nothing has gone wrong.

    **What to do:** check back with [`onboarding_status`](/reference/mcp/tools#getting-started) once
    the account holder says they're done, then ask again.
  </Accordion>
</AccordionGroup>

## 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](/reference/mcp/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.