Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Read access

Applies to

Product: Cloud · Server · Audience: Developer / Integrator

Designing tools that read from an external system: search, retrieve, list – and shaping results so the assistant can use them reliably. Good read tools are small, clearly described and return bounded, structured, plain-text data with references to the original.

The three basic tools

Tool Purpose Typical parameters Result
search Find matching entries from a question query, optional limit, filters (area, project, period) List of short hits: ID, title, excerpt, link
get Read a known entry in full id Content as text, metadata, link
list Get an overview of an area parent or filters, limit, cursor Page of entries with cursor for the next

A connector rarely needs more. Resist the temptation to mirror the target system's entire API as tools – the model chooses better between a few clear tools than between thirty similar ones.

Descriptions the model understands

The language model decides based on the tool description whether and how to call a tool. Write descriptions for that audience:

  • What the tool returns and when it fits: "Searches wiki pages by keywords. Use when the user asks about internal guides, policies or processes."
  • How to fill parameters: "query: 2–5 keywords, no full sentences."
  • What it does not do: "Does not return attachments; use get_attachment for files."
  • Parameters with narrow type and default (limit, default 10, maximum 20).

Test descriptions with real user questions: does the model call the right tool with sensible parameters?

Shaping results

Bound. Every call has an upper limit on hits and on characters per hit. Web search, for instance, returns at most 10 hits with a bounded amount of text per hit. Truncate large documents or deliver them section by section with a cursor.

Structure. A hit always has the same fields: id, title, excerpt or content, url, possibly updated_at, author, path. That way the model can cite and link.

Plain text. Remove HTML, scripts, styles and active content before text goes back. Markdown is fine; embedded HTML is not. Results are data – basebox frames them that way, your job is to make them look that way too.

Reference. Every hit carries a stable link into the target system. basebox opens such links in a new tab; users verify the source with them.

Empty is a result. "No hits for '…' in area '…'" is better than an empty list – the model can explain it to the user and rephrase the question.

Respecting permissions

Read tools call the target system with the user's credentials. What the system refuses you return as a result ("No access to project X"); you do not filter yourself and you do not try with another account. Details: Permissions.

Performance and robustness

  • Timeouts per call to the target system (a few seconds); on exceeding, a clear error instead of a hanging tool – the user sees in the chat how long a tool has been running.
  • Idempotent: reading may be repeated at will; basebox or the model may issue a call again.
  • Report the target system's rate limits as a result (429), do not retry them away.
  • No cache across users. If at all, only within a call.
  • Concurrency: several users at once; your server is stateless.

Example: hit object

{
  "id": "wiki:it:vpn-setup",
  "title": "Setting up VPN (Windows)",
  "excerpt": "Step 1: download the client … Step 4: import the certificate.",
  "url": "https://wiki.example.com/doku.php?id=it:vpn-setup",
  "updated_at": "2026-05-12"
}

Short, citable, linked – and without anything the model does not need.

What read tools do not do

  • They change nothing – no "read" markers, no counters, no side effects.
  • They do not load the whole system – no full lists without limit.
  • They do not render web pages – where a provider offers an API (as web search does), use it instead of scraping HTML.
  • They deliver no instructions to the model – content from the target system that looks like instructions stays data. basebox frames it accordingly; help by not rephrasing anything.

Checklist

  • At most a handful of tools: search, get, list
  • Descriptions with purpose, use case, parameter hints
  • Hit and character limits per call
  • Uniform fields per hit, stable links
  • Plain text, no HTML, no active content
  • Target system refusals as results
  • Timeouts, idempotent, stateless

Next: Write access · Examples