Control when the assistant looks up

Documents turn lookup on. Linking the Knowledge Base tool to an assistant opts that assistant into when-to-call instructions. You do not create that tool. OnCore provides one, shared by every tenant. Your text is stored separately, so two tenants can give the same tool different instructions.

If the tool is not on the assistant, lookup still runs from the documents, using the original default. That is the same path as before this feature.

What the assistant is told by default#

If the tool is linked and you have not set your own when-to-call text, the assistant is told to look up the knowledge base when the caller asks something whose answer depends on information specific to this assistant. The numbered step repeats that same when-to-call rule.

That default is too wide for some assistants. A restaurant that already has an hours tool still looks the knowledge base up for takeout, unless you say otherwise.

Set when to look this up for one assistant#

Write one sentence that names the topics that should trigger a lookup. Leave how to call the tool alone. OnCore keeps the how-step as Call kb_lookup, then answer from what it returns.

The assistant is then told:

### **Knowledge Base**
Only look this up when the caller asks about parking.
1. Call kb_lookup, then answer from what it returns.

The default paragraph and the default numbered step are both gone. If you only replaced the paragraph and left the old step, the assistant would still look the knowledge base up for any assistant-specific fact.

From the dashboard#

1. Open the assistant.
2. Open the Knowledge Base tab and attach at least one enabled document. Lookup is off until you do.
3. On the Configuration tab, check Knowledge Base under Tools and save. That opts this assistant into when-to-call instructions. Unchecking it later goes back to the original lookup. It does not disable the documents.
4. Return to the Knowledge Base tab. In When to look this up, write the when-to-call sentence.
5. Save.

To restore the OnCore default, clear the field (or click Restore default) and save. Both default lines come back.

From the API#

Find the Knowledge Base tool, link it to the assistant, then set the description override.

GET /tools?includeGlobal=true includes platform-provided tools. The Knowledge Base tool is the one named Knowledge Base. You cannot create, rename, or delete it.

curl "https://core-api.heysadie.ai/tools?includeGlobal=true&limit=500" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Add that tool id to the assistant's toolIds with PATCH /assistants/{id}. The link is required. PUT on a tool that is not linked returns Tool is not linked to this assistant.

Then set the when-to-call text:

curl -X PUT "https://core-api.heysadie.ai/assistants/0195f1e2-0000-0000-0000-000000000000/tools/0195f1e2-0000-0000-0000-000000000002/description-override" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Only look this up when the caller asks about parking."
  }'

data.message is Description override set, or Description override cleared when you send an empty string.

GET /assistants/{id}/tools/{toolId}/override returns description when one is set. That is the same string the dashboard shows in When to look this up.

Set tenant-wide Knowledge Base instructions#

The tool page instructions editor changes the default for every assistant in your tenant that has not set its own when-to-call text. You still PUT against the OnCore Knowledge Base tool id. OnCore stores your copy separately. Other tenants keep the OnCore default, or their own copy.

This path is only for the Knowledge Base tool. PUT or DELETE against any other tool id returns 403.

{id} is the Knowledge Base tool id from GET /tools?includeGlobal=true. The body is the same instruction object other tools use: a title, a description, and at least one step.

curl -X PUT "https://core-api.heysadie.ai/tools/0195f1e2-0000-0000-0000-000000000002/instruction" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": {
      "title": "Knowledge Base",
      "description": "Only look this up for hours, parking, or allergens.",
      "steps": [
        {
          "action": "Call kb_lookup for hours, parking, or allergens. Do not guess.",
          "wait_for_response": false
        }
      ]
    }
  }'

A description-only body (no steps) is a 400.

GET /tools/{id} returns the instruction this tenant currently uses. hasTenantInstruction is true after a successful PUT, and false after DELETE.

DELETE /tools/{id}/instruction removes your tenant's copy. Assistants that still have their own when-to-call text keep it.

Which text the assistant uses#

The assistant when-to-call text is the one that must be taken as the whole when-rule. Do not also leave a tenant step that says "call for any assistant-specific fact."

Text conversations#

Everything above applies to text conversations (SMS, WhatsApp and web chat) too, until you give the Knowledge Base tool text instructions. Then text conversations follow those instead, and calls keep the instructions above.

• Tenant-wide. PUT /tools/{id}/instruction takes an optional textInstructions next to the required instruction, same shape. While your tenant copy exists it replaces both of the OnCore defaults, so a copy with no textInstructions means text conversations use your instruction. Leave textInstructions out of a later PUT to keep it; send null to remove it. DELETE /tools/{id}/instruction removes both. GET /tools/{id} returns the textInstructions your tenant currently uses.
• One assistant. PUT /assistants/{id}/tools/{toolId}/text-description-override sets the when-to-call text for text conversations, with the same body and the same empty-string reset as description-override. Read it back with GET /assistants/{id}/tools/{toolId}/text-override.

The text when-to-call text only takes effect while the Knowledge Base tool has text instructions. Without them, text conversations use the voice chain, including this assistant's description-override.

Next steps#

• Knowledge base overview: what documents do on a live call.
• Manage documents: upload documents and attach them so lookup can run.
• Instruction overrides: the same override surface for other tools.