---
title: Working with the tools of Talemo
summary: Which business a call is for, how to show a change before making it, what a refusal looks like and which refusals are plain answers; the tools that need no business, and how to read this guide.
tools: [talemo_ready, talemo_list_businesses, talemo_get_zone_currency, talemo_find_guide_topics, talemo_get_guide_topic]
related: [../account/connected-programs-and-keys, ../account/team-and-roles, ../kits/industry-kits, ../money/low-balance-stages, ../knowledge/knowledge-search]
search: [Talemo MCP server, Talemo API for AI agents, how to use Talemo tools, connect Claude to Talemo, ChatGPT connector Talemo, business_id, dry_run preview before change, MCP tool error codes, not enough money on the balance error, refusal, auth.required, role.forbidden, kit.required, billing.credits_exhausted, billing.blocked]
---

# Working with the tools of Talemo

Talemo is the record layer of a service business, and its tools go through the
same product API as the web and the mobile app. Whatever the product enforces —
rights of a role, rules of a branch, the check that a booking does not overlap —
applies to a tool as well. A tool is never a way round a refusal.

## Which business a call is for

A tool that works on the data of a business takes `business_id`.

- **A business key on a computer** (Claude Desktop and other programs) acts on
  behalf of the person who created it, in one business only. `talemo_list_businesses`
  names that business, and its ID goes in `business_id`.
- **A connection of Claude or ChatGPT** acts with the rights of the person who
  connected it, in the businesses they chose when connecting. `talemo_list_businesses`
  names those businesses; the ID of one of them goes in `business_id`. The person
  changes the choice by connecting Talemo again.
- A business that is not on the list is refused with `door.business_forbidden`.
  A missing, revoked or expired key is refused with `auth.required`: the person
  creates a new key (see [Connected programs and access keys](../account/connected-programs-and-keys.md)).

`talemo_list_businesses` also shows each business with its open branches, the time
zone of every branch and the `vertical` of the business. The industry decides what
the business calls its masters, places and devices, so say these words to the person
as their industry does (see [Industry kits](../kits/industry-kits.md)).

Three tools need no business: `talemo_ready` says whether Talemo and its database are
answering, `talemo_list_businesses` names the businesses, and `talemo_get_zone_currency`
names the usual currency of a time zone — to ask the person about, never to set on
its own. The two tools of this guide need none either.

## Showing a change before making it

Every tool that changes something takes `dry_run`. With it nothing changes, and the
answer is what the change would be — or the refusal it would get. Show the person
the preview, and make the real call after they agree.

A tool that changes a lot at once says so in its description. Never make its real
call before the person has seen its `dry_run` and said yes.

## A refusal is an answer

A refused call comes back as a tool error with `code`, `status`, `params` and `hint` —
why it was refused and how to fix it. Most refusals are legitimate answers, not
failures: the product says what the state of the business allows. Tell the person, and
change the plan; do not retry the same call.

- **Status 409** — the state forbids the call: a time already taken (`slot.overlap`),
  a resource with bookings ahead (`resource.has_bookings`), a way to reach that belongs
  to another contact (`contact.taken`). The code and `params` name what to change.
- **`role.forbidden`** — the role of the person has no right for this; `params.capability`
  names it. Tell the person; it is not something a tool can change.
- **`role.field_forbidden`** — a field of a card is closed to the role. Closed fields
  are missing from the answers, and sending one is refused.
- **`kit.required`** — the tool belongs to an industry kit that is not installed in this
  business; `params.kit` names the kit. The tools of such a kit are not in the list
  for it.
- **`not_found`** — there is no such record, or the role sees only its own records and
  this one is not its.
- **`request.body_invalid`** — an argument is wrong; `params.field` names it.
- **`auth.required`** — the connection is not allowed to do this. Where Talemo
  reserves a change for a person (knowledge, service languages, rights of the online
  admin), it means "the person does it in Talemo", and the connection is not broken.
- **`client.…` and status 0** — the product did not answer as expected, or did not
  answer at all. This is not a verdict on the request: try again later.

## When the balance runs out

A business pays for its work with money in dollars (see [Low balance and blocks](../money/low-balance-stages.md)).
Status 402 with `billing.blocked` means the hard block, and any tool of a business
can give it: until a person tops the business up on the website of Talemo, nothing
of the tools of a business works but `talemo_get_billing`, and `params.deletesAt`
says when the business goes to the archive. `talemo_ready`,
`talemo_list_businesses`, `talemo_get_zone_currency` and both tools of the guide
work even then. Status 402 with `billing.credits_exhausted` is given not by any tool
but only by an operation that spends money on AI: it means the balance is down to
the reserve, AI stops in the business until a top-up, and the tools without AI keep
working. Neither is a failure. A tool cannot pay, so tell the person.

## Reading this guide

`talemo_find_guide_topics` finds topics of the guide: pass `query` with the words
of a question or the name of a tool, `module` to list one folder, or nothing for the
contents. `talemo_get_guide_topic` reads one topic whole by its id, like
`booking/visits`.

Read the topic of a module before acting in it if you have not worked in it during
this conversation. Every tool description ends with its topic as `Guide: folder/slug.`
The same topics are public at talemo.app/docs.

The guide tells how Talemo works. What a business itself says to its clients — prices
it names, rules it keeps, its voice — is its knowledge, and it is found with
`talemo_find_knowledge` (see [Searching the knowledge](../knowledge/knowledge-search.md)).