---
title: codespar_get_started
description: Read-only setup planner, read live. In Test it reads the project account, its balance and its active mandates, then returns the next step that can actually run. Moves no money.
---

import { Callout } from "fumadocs-ui/components/callout";

<MetaToolHeader tool="codespar_get_started" />

Call it first when a user opens with "how do I start" or "what can you do". It saves the agent a discovery detour: instead of guessing at tool names, it gets the sequence that works for this workspace in this environment.

## Actions

<MetaToolActions tool="codespar_get_started" />

## Example

The tool takes no arguments: workspace, project and environment all derive from the API key on the session.

<Split min={380}>
<SplitPane label="The same call, four ways">

<Tabs items={["MCP", "TypeScript", "Python", "CLI"]}>
<Tab value="MCP">

```json title="arguments"
{
  "name": "codespar_get_started",
  "arguments": {}
}
```

</Tab>
<Tab value="TypeScript">

```ts
const result = await session.execute("codespar_get_started", {});
```

</Tab>
<Tab value="Python">

```python
result = session.execute("codespar_get_started", {})
```

</Tab>
<Tab value="CLI">

```bash
codespar tool codespar_get_started \
  -i '{}'
```

</Tab>
</Tabs>

</SplitPane>
<SplitPane label="Result · Test, a funded account with no mandate">

```json title="result"
{
  "environment": "test",
  "summary": "You're in the CodeSpar test environment: no real money moves, and Pix in and out need no bank connection, CNPJ or KYC. The project's Test account holds R$ 969,26 now (R$ 969,26 available), so it needs no top-up.",
  "binding": { "environment": "test", "project_id": "prj_…", "consumer_id": "sbx_prj_…" },
  "account": { "kind": "account", "balance_minor": 96926, "available_minor": 96926, "currency": "BRL" },
  "mandates": [],
  "happy_path": [
    { "step": 1, "title": "Read the Test account", "tool": "codespar_wallet", "detail": "action=balance reads the spendable balance and the account's Pix key; action=statement reads its movements. …" },
    { "step": 2, "title": "Receive a Pix", "tool": "codespar_charge", "detail": "Issues an inbound Pix charge on the Test rails (the buyer pays you). No mandate is needed to receive." },
    { "step": 3, "title": "Pay under a signed mandate", "tool": "codespar_pay", "detail": "This project has no active mandate, so codespar_pay refuses and sends nothing. … Only a person creates and signs one, in the CodeSpar dashboard under Agents …" }
  ],
  "tools": {
    "ready": ["codespar_get_started", "codespar_wallet", "codespar_ledger", "codespar_charge", "codespar_discover", "codespar_manage_connections"],
    "need_setup": [{ "tool": "codespar_pay", "reason": "needs an active mandate signed by a person (dashboard, Agents)" }, "…"]
  }
}
```

</SplitPane>
</Split>

The plan is read at call time, never assumed:

- **Binding.** `binding` names the environment, the project and the consumer that `codespar_wallet` and `codespar_ledger` read by default. On the hosted connector and in a conversation, that is the project's Test account, the one the Wallet page shows.
- **Account, four cases.** `account.kind` is `account` (the balance as it is now, zero included), `preparing` (the Test account is being prepared), `not_permitted` (the key lacks `wallets:read`, named in `required_scope`), or `account` is `null` (the read failed now). None of them means "fund the wallet". The R$ 1.000 a Test account starts with is its initial credit, not its balance.
- **Mandates.** `mandates` lists the project's active mandates: whose account pays (`consumer_id`), the agent it names, the per-payment cap, what is `remaining_minor` of the cap, how many payees it allows and the expiry. With none, the plan says that only a person creates and signs one, in the dashboard under **Agents**, and `codespar_pay` moves to `tools.need_setup`.
- **Tools.** `tools.ready` acts now; `tools.need_setup` needs a connection or a person's setup first, each with its reason.

A `csk_live_*` key gets a path that starts with onboarding and connecting real rails, since live settlement needs a funding source before it can move money.

<Callout type="warn" title="A store checkout in Test is a real order at the store">
`codespar_shop` runs the store's real checkout in Test too: it places a real order at the store, awaiting payment, with demo buyer data for any field not given. The Pix that is then paid is a test substitute minted for the same total to the platform's test receiver, so the store is never paid and its order stays unpaid. Tell the person before a Test checkout.
</Callout>

## When to use

- **The first turn of a setup conversation.** The result is a structured, ordered plan the agent can follow step by step, each step naming the tool to call and how.
- **Before deciding anything.** It is read-only, so it is safe to call on every fresh session.
- **Not for an open intent** ("buy a TV"): that is [`codespar_discover`](/docs/concepts/meta-tools/discover).

## Arguments

None. The published schema declares no properties. Any argument passed is ignored.

## Errors and what to do

| Error | Cause | What to do |
|---|---|---|
| The tool is the only one visible | The API key is missing or invalid: setup mode exposes exactly one tool, the no-key setup tool that mints a key, under this same name. | Mint or fix the key, then reconnect; the authenticated tool then hands back the happy path. |
| `account.kind: "not_permitted"` | The key or connection lacks `wallets:read`. | A person grants it in the dashboard under **API keys**. Never ask for a key or any secret in the conversation. |
| `account` is `null` | The balance could not be read now. | Read it with `codespar_wallet` `action=balance`; this is a read failure, not an empty account. |

## Money and mandate

Nothing moves, by construction. The tool returns text: it creates no payment, no charge, no connection and no wallet, and it takes no argument that could target a counterparty. Nothing it returns has a side effect until the agent calls one of the tools named in the plan, each under its own gates.

## Related

- [`codespar_discover`](/docs/concepts/meta-tools/discover): use it for an open intent once you are past setup
- [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections): connect the rails the plan asks for
- [Test mode](/docs/concepts/test-mode): what the sandbox rails do and do not do

## Notes

**One name, two tools.** Exactly one `codespar_get_started` is ever visible. With no valid key the MCP server exposes its setup tool, which mints a key. Once a valid key is present the server exposes the backend meta-tools instead, and this one hands back the happy path. An agent with no usable key gets exactly one thing it can do, not a catalog it cannot call.

**Result shape (SDK), as previously documented.** `{ environment: "live" | "test", summary, happy_path: Array<{ step, title, tool, detail }>, notes: string[] }`, which is the shape of the example above. This revision did not re-run the call to confirm the wording of the current plan.