How to organize your Agents knowledge
📋Tables
When to Use
Tables are structured, live databases. Each row is a record. Each column is a typed field. The agent reads, creates, updates, and deletes via Table Actions.
Use Tables when:
Data changes frequently and needs to be written by the agent in real time
Data has a fixed, predictable structure — defined columns with types
You need to persist information across conversations
The use case involves CRUD operations
Examples:
Leads: name, email, phone, status, contact date
Inventory: SKU, name, price, stock
Schedule: client, date, time, service type
Tickets: ID, description, status, assignee
Golden rule: if the agent is going to write to that data, it's a Table.
URL and Image Columns
Tables work with typed columns. Beyond the basic types (text, number, boolean, date), there are two specialized types for external references.
URL Column
Stores web addresses as the primary cell value. The system recognizes that field as a link — not generic text.
When to use:
Each record has an associated link the agent needs to return
Catalogs with a link to a purchase page
Articles with a link to external access
Records with links to forms, videos, or landing pages
Example:
Table: Course Catalog
name (text): “Advanced Digital Marketing”
category (text): “Marketing”
price (number): 497
enrollment_link (URL): “https://site.com/courses/marketing”
active (boolean): true
Image Column
Stores URLs pointing to image files. The difference from the URL type is visual semantics — the system knows the content is an image.
When to use:
Product catalogs with photos
Digital menus
Portfolios with thumbnails
Profiles with avatars
Example:
Table: Menu
name (text): “Grilled Chicken”
price (number): 18.90
photo (image): “https://cdn.restaurant.com/chicken.jpg”
available (boolean): true
Content
Any link
Link to an image file
Rendering
Clickable link
Image displayed (where supported)
Typical use
Page, form, video
Product photo, thumbnail
Semantic Search and Non-Searchable Items
Semantic search in Tables is fundamentally different from a SQL query.
Exact match:
Semantic search: Query: "sports footwear for running" → Finds: "Nike Air Max Sneaker", "Adidas Running Shoe" → Even with no words in common with the query
Searchable vs Non-Searchable Columns
Not all columns should be included in the semantic index.
Include in embedding:
Descriptive fields: name, description, category, tags
Fields the user will reference in natural language
Exclude from embedding:
Internal IDs (
PRD-00847)Dates and timestamps
Booleans (
true/false)Exact numeric values (
97.50,12)URLs and images
Internal control fields
Including non-semantic fields pollutes the index. The model cannot create meaningful embeddings from
"true"or"PRD-00847". This reduces search precision with no benefit.
How to Handle Non-Searchable Items
📍Strategy 1 — Separate search from filtering
The agent first runs semantic search on descriptive columns, then applies exact filters on numeric/boolean columns.
User: "I want running sneakers under $100 that are in stock"
Semantic search: "running sneakers" → name, description, category columns
Filter: price <= 100 AND available = true
Returns items that passed both
📍Strategy 2 — Derived text fields
To make normally non-searchable data easier to query, create an auxiliary column that describes it:
price_range (text): "budget" / "mid-range" / "premium" -- Instead of letting the search try to interpret "89.90"
📍Strategy 3 — Explicit prompt instruction
"When searching for products in the Table, use semantic search on the 'description' and 'category' fields. Then filter by 'available = true'. For price range, use the 'price_range' field, not the numeric field."
📚 Knowledge Base
When to Use
Knowledge Bases are knowledge repositories for semantic lookup. The agent does not write to them — it only reads via the Knowledge Base Search Tool.
Use a Knowledge Base when:
Content is textual, unstructured, or semi-structured
Content is meant to answer questions, not to be manipulated
Volume is too large for the Prompt (above ~5000 characters)
Content changes editorially — you update it, not the agent
You need similarity-based semantic search
Examples:
Golden rule: if the agent is only going to read/consult, it's a KB (if long) or Prompt (if short and static).
Query Scoped by Document
By default, KB Search scans all documents in the base simultaneously. A scoped query restricts the search to one specific document.
When to Use
KB with documents from very different contexts
Multi-context agent with dynamic scoping
Compliance and information isolation
Very large KBs
Scoping reduces the search space and improves both precision and speed.
How to Implement in the Prompt
When Not to Scope
The question is genuinely cross-document
You don't know in advance which document is relevant
Small KB with few homogeneous documents
📄 PDF Reader Tool
When to Use
Use when the document does not exist beforehand — it is brought by the user at the moment of interaction.
Use cases:
The document is different for every user. It makes no sense to index it in a KB because each instance is unique. The agent only needs the content for that conversation.
PDF Reader vs Knowledge Base
When the document exists
At runtime (user sends it)
Pre-loaded in configuration
Who provides it
The user, during the conversation
The agent creator
Reading type
Direct file reading
Semantic search on vector index
Persistence
Temporary (lasts the conversation)
Permanent
Volume
One document at a time
Multiple indexed documents
Pitfall: using KB to process documents the user sends. KB does not accept uploads at execution time.
Pitfall: using PDF Reader for documents that are always the same. Inefficient — processes the same file repeatedly with no semantic search.
Using Both Together
There are scenarios where both make sense in the same solution.
Contract analysis agent:
Onboarding agent:
Last updated