Skip to main content

How aiChat works

Combine prompts, skills, and tools to get helpful info

Written by Holly Conrad Smith

Every message you send kicks off a request that bundles your active skills, the tools available at that point in the conversation, and your conversation history — the LLM uses that to decide what to say and which tools to call. Skills and tools work together but do different jobs: tools give the AI capability, while skills give it judgment about when and why to use it.

How the AI works

  1. Your message

  2. API Request

    1. system All active skills concatenated into one cached block

    2. tools Only the tools the request needs right now: a small always-on set, plus any capability groups already activated in this conversation

    3. messages Conversation history

  3. LLM Decides

    1. Skills tell it when and why to act

    2. Tool descriptions tell it how

      → Text response shown to you

      → Tool calls executed by the app

  4. Tool Execution

    1. Read tools → auto-executed

    2. Mutation tools → you approve/reject

    3. Results sent back to LLM · Loop continues until done

Tools vs Skills

Tool

Skill

What

A function the AI can call

Markdown instructions in the system prompt

Gives the AI

Capability — "here is a function and its parameters"

Judgment — "when to use it, why, and what to watch out for"

Defined in

Code (tools.ts) — wrappers around Giraffe SDK RPC functions. If a tool isn't available in the core set, the AI can call any Giraffe SDK function directly via invoke_rpc / get_state, and look up docs first via fetch_docs.

Markdown (.md files) — editable in Settings. Create your own or modify the built-in core skills.

Togglable

Not by hand — most tools activate automatically in groups the first time a request needs them

Yes — toggle off to remove from prompt and save tokens

Example

updateUsages({ usages: {...} })

"Only call updateUsages when user says 'assumptions'. For buildings, use updateSections."

Capability gating

Most tools sit behind a one-time activation call instead of loading into every request from the start. Before the AI can call a tool like getLayers or updateUsages, it first calls a meta-tool for that tool's group, such as use_layers or use_usages. Once a group is activated, it stays activated for the rest of the conversation.

A small set of tools skips this step and is available from your very first message: flyTo, getMapLocation, queryJSON, create_artifact, get_state, invoke_rpc, web_search, and web_fetch.

This keeps each request lean. Asking about layers doesn't pull in the parcel search or analytics tools, so a request only carries the tool definitions it's actually likely to use.

Watch this happen turn by turn. Turn on Show prompt inspector in the status bar (see Getting started with aiChat) to see exactly which tools were sent with a given request.

Available tools

Tools are functions the AI can call. It reads the tool name and description to decide which one to use. Skills provide the behavioral guidance for when and why.

Group

Tools

Activated by

Always available

flyTo, getMapLocation, queryJSON, create_artifact, get_state, invoke_rpc, web_search, web_fetch

No activation needed

Layers

getLayers, setLayerVisibility, getLayerContents, filterLayerFeatures, styleLayer, organizeLayerTree

use_layers

Sections

findSections, createSections, updateSections, deleteSections

use_sections

Usage Types

getUsages, updateUsages, deleteUsages

use_usages

Flows

list_lightning_bolt_flows, fetch_lightning_bolt_flow, add_lightning_bolt_flow, getProjectFlows, addFlowToGeometry

use_flows

Parcels

searchParcelsAU, regridParcelSearch, regridParcelQuery, downloadRegridLayer

use_parcels

Giraffe Analytics

getAnalytics, updateAnalytics

use_analytics

Content Library

fetch_content_packs, fetch_pack_contents, add_content_pack_to_project

use_packs

SDK Docs

get_functions_doc, get_state_doc, fetch_docs

use_sdkDocs

Did this answer your question?

Related Articles