The AI module, explained field by field — for absolute beginners

This guide assumes you've never configured anything like this before. Every term gets explained the first time it shows up. We'll use one running example the whole way through: a capability that looks up a resident's property-tax (arnona) balance.

What is "the AI module," really?

When people at Kav say "the AI module," they mean one specific part of a capability's setup screen: the part that isn't code, and isn't a connection to your billing system — it's a handful of text boxes that tell the AI assistant when it's allowed to use this tool, and when it should leave it alone. Nothing here talks to your database. It only talks to the model.

Think of it like a name tag and a job description you'd hand a new employee before their first shift: "here's what you do, here's when to step in, here's when this isn't your job."

use_when — telling the AI when this is the right tool

This is a short piece of text, written as if you're speaking directly to the assistant ("use this when…"), describing the situations where this capability is the right one to reach for.

For the arnona-balance capability, good examples look like:

• "Use this when a resident asks how much property tax they currently owe, or asks about their arnona balance."
• "Use this when a resident asks whether they have an outstanding property-tax debt."
• "Use this when a resident asks for the amount due on their property tax, for this year or a past year."

What makes these good is that they sound like something a real resident would actually type or say — not the internal, formal name of a database table. The assistant matches a resident's own words against this text, so the closer this text sounds to a real question, the more reliably it gets picked.

do_not_use_when — telling the AI when to stay out of it

This one matters more than it looks like it should. In practice, telling the assistant what not to do with a tool prevents more wrong answers than a perfect use_when ever could, because it's the field that stops the wrong tool from getting picked when two capabilities sound similar.

For the same arnona-balance capability:

• "Do not use this for water bills, business licensing fees, or any charge that isn't property tax."
• "Do not use this to explain how the property-tax rate itself is calculated — that's a knowledge-base question, not a balance lookup."

summary — the first sentence the model ever reads about this tool

One sentence. This is the very first line of the description the assistant sees when it's deciding what tools exist at all — before it even gets to use_when. For our example: "Looks up a resident's current property-tax (arnona) balance."

disambiguation — what to do when it's genuinely unclear

Sometimes a resident's question could reasonably go more than one way — say, they own two properties and just ask "what do I owe?" This field tells the assistant what to do in exactly that situation: for example, "If the resident has more than one property, ask which property before answering." This text is attached to the tool's description exactly as written, word for word.

grounding — how sure the assistant is allowed to sound

This field answers a question you might not think to ask: when this capability returns something, how certain is that result? There are four options:

• Answer — the result genuinely is the answer, checked again against what the capability promised to return. Pick this for something like our balance lookup: a real number, straight from your system.
• Signpost — the result only points toward where an answer might be, the way a road sign points toward a town without being the town itself. Use this for something like a search result that names a likely source, not a confirmed fact.
• Measured — how well the result matches the question is scored separately from the result itself. This is for more search-like capabilities.
• Platform — the result is the platform's own built-in knowledge about how Kav itself works, not something fetched from your systems.

For almost every capability that fetches one specific fact or number from your own system — like our balance lookup — Answer is the right choice. This setting quietly controls whether the assistant is allowed to present what it got back as a fact, or has to hedge.

Synonyms — the field with a genuine gotcha

Synonyms are alternate search phrases that help the assistant's search recognize a resident's own wording — entered one per line, in the form language=term, for example:

he=ארנונה
he=מס רכוש
en=property tax

The contract: what the resident gives, and what you promise back

The contract is a second, separate part of the setup — a table, not a paragraph, because it's really answering two very concrete questions: what does the resident have to tell us, and what do we promise to hand back. There's one table for what comes in, and one for what goes out.

Each row in the table has:

• Field name — a short internal name for this piece of information, like propertyId.
• Type — what kind of value this is. There are exactly six choices: text, number, whole number, yes/no, date, or a list of texts.
• Required (on the incoming side) or Always returned (on the outgoing side) — a checkbox. On the incoming table, checking it means the resident must supply this before the capability can run. On the outgoing table, checking it means this field will be present in every single response, not just sometimes.
• Description — a plain sentence describing the field. This column is not just a note for other humans reading the form later — it's read by the AI model itself, the same way the use_when text is. A vague description here can make the model use a field wrong, exactly the way a vague use_when can make it pick the wrong tool.

If the whole answer is a list of things rather than one thing — say, a list of past bills instead of one balance — there's a simple toggle for that, and the table below it describes just one item in that list.

The advanced escape hatch you'll probably never need

For the rare case where a field is more complicated than the table can express — a nested structure, or a value that has to be one of several very specific shapes — there's a raw text editor sitting one click away, where you can write the underlying schema directly. If you never see this screen, that's a good sign: it means every field you've needed so far was simple enough for the table to handle on its own.