Tools: reading your site

These tools read a site without changing it. None needs an open turn. See the Tool reference for conventions and shared errors.

list_pages

Lists the site's pages: each page's address (route), file, whether it's a CMS item page, and the components it uses. The entry with route __layout is the layout shared by every page, including the header and footer.

When to use it: To see what pages exist before adding or changing one.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "pages": [
    {
      "route": "/",
      "filePath": "src/pages/index.astro",
      "components": [
        {
          "name": "Hero",
          "importPath": "../components/sections/Hero.astro",
          "isRegistered": true,
          "structureLocked": false,
          "props": {},
          "contentKey": null,
          "line": 21
        }
      ]
    },
    {
      "route": "/:slug",
      "filePath": "src/pages/[slug].astro",
      "components": [],
      "isDynamic": true,
      "contentType": "post"
    }
  ]
}

get_site_structure

A one-call overview: the top-level pages with the components each uses, plus all components grouped as layout, sections and ui.

When to use it: As a starting point on a site you haven't seen.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

The result lists pages with their components, and the component list grouped by category.

inspect_page

Shows a page's structure: its sections in order, what it imports, and the props passed to each section.

When to use it: Before editing a page. It's quicker to read than the raw file.

Needs an open turn: No.

Input	Type	Required	Meaning
page	string	Yes	The page's address (/, /about) or file name (index.astro).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "page": "/about"
}

Example result

The result lists the page's sections in order with their props.

Errors

You see	What it means	What to do
Page not found	No page matches.	Check the address with list_pages.

list_components

Lists every component on the site with its file, description, props and category.

When to use it: Before creating a component, to reuse one that already exists.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

The result lists each component's name, path, description, props and category.

inspect_component

Shows one component: its category, description, editable props, the pages that use it, and its source.

When to use it: Before editing a component or passing it new props.

Needs an open turn: No.

Input	Type	Required	Meaning
component	string	Yes	The component's name (Hero) or path (src/components/sections/Hero.astro).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "component": "DocsHome"
}

Example result

COMPONENT: DocsHome
Category: sections
Description: Docs home
Editable props: heading, intro, sections
Used on: / (line 21)

--- Source ---
---
import copy from '../../../content/components/sections/DocsHome.json'
…

Errors

You see	What it means	What to do
Component not found	No component has that name or path.	Check the name with list_components.

list_files

Lists the files and folders in one folder of the site. Hidden files, installed packages and build output are left out.

When to use it: To browse the site when you don't know a file's path.

Needs an open turn: No.

Input	Type	Required	Meaning
path	string	No	Folder to list, relative to the site root, such as /src/components. Default /.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "path": "/"
}

Example result

{
  "path": "/",
  "entries": [
    {
      "name": "brand",
      "type": "dir"
    },
    {
      "name": "content",
      "type": "dir"
    },
    {
      "name": "src",
      "type": "dir"
    },
    {
      "name": "site.json",
      "type": "file",
      "size": 282
    }
  ]
}

read_file

Reads a site file. With startLine and endLine, it returns only those lines, numbered.

When to use it: To read code before changing it. After a search_files hit, read just the lines around it.

Needs an open turn: No.

Input	Type	Required	Meaning
path	string	Yes	File path relative to the site root, such as src/pages/index.astro.
startLine	integer	No	First line to return (from 1).
endLine	integer	No	Last line to return. Leave out to read to the end.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "path": "src/pages/index.astro",
  "startLine": 1,
  "endLine": 4
}

Example result

1	---
2	export const prerender = false
3	
4	import { getLiveCollection } from 'astro:content'

Errors

You see	What it means	What to do
File not found	There's no file at that path.	Check the path with list_files or search_files.

search_files

Searches the site's code and text for a pattern and returns each match with its file, line and column. It searches src/, content/, brand/ and site.json.

When to use it: To find where some text, a class, a component or an import lives, before reading files.

Needs an open turn: No.

Input	Type	Required	Meaning
pattern	string	Yes	A regular expression, or plain text with literal. Up to 256 characters. Lookaround and backreferences aren't supported.
literal	boolean	No	Treat pattern as plain text. Default false.
ignoreCase	boolean	No	Ignore upper and lower case. Default false.
path	string	No	Limit the search to one file or folder, such as src/components.
glob	string	No	Only search file names matching this, such as *.astro.
maxResults	integer	No	Most matches to return. Default 50, maximum 200.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "pattern": "data-component=\"DocsHome\"",
  "literal": true
}

Example result

{
  "pattern": "data-component=\"DocsHome\"",
  "path": "/",
  "matches": [
    {
      "path": "src/components/sections/DocsHome.astro",
      "line": 19,
      "column": 10,
      "text": "<section data-component=\"DocsHome\" class=\"bg-cream\">"
    }
  ],
  "totalMatches": 1,
  "truncated": false
}

Errors

You see	What it means	What to do
truncated: true	There were more matches than maxResults.	Narrow the search with path or glob.
Invalid pattern	The pattern isn't a valid regular expression.	Fix it, or set literal to true.

get_tokens

Reads the site's design tokens: colors (scales and single swatches), font families, and page defaults.

When to use it: Before styling anything, to know which color and font names exist.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "colors": {
    "scales": {},
    "swatches": {
      "white": "#ffffff",
      "ink": "#141B2D",
      "accent": "oklch(0.8396 0.2522 27.01)"
    }
  },
  "textStyles": {},
  "typography": {
    "fontFamily": {
      "heading": "'DM Sans', ui-sans-serif, system-ui, sans-serif",
      "body": "Inter, ui-sans-serif, system-ui, sans-serif"
    }
  },
  "elementDefaults": {
    "body": {
      "classes": "min-h-screen bg-white font-body text-ink antialiased"
    },
    "h1": {
      "classes": "font-heading"
    }
  }
}

Use the names as Tailwind utilities: swatch ink gives text-ink and bg-ink; font heading gives font-heading. textStyles is always empty; text styles aren't available.

get_brand_guide

Reads the site's brand guide, the instructions Starjay's built-in AI reads on every request.

When to use it: Before making design or writing decisions, to follow the site's voice and style.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "content": "# Voice\nWarm, plain, short sentences…",
  "exists": true
}

list_backups

Lists the site's checkpoints: the automatic ones and the ones the user saved.

When to use it: To tell the user which checkpoints exist. Your agent can't restore one; the user restores checkpoints in the editor.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "backups": [
    {
      "id": "bp_…",
      "siteId": "0APMiuxGY2yB4xJm5BilJ",
      "description": "Before AI session",
      "trigger": "auto-ai",
      "createdAt": "2026-10-17T19:54:33.584Z",
      "fileCount": 35
    }
  ]
}

Related

• Tools: editing
• Project files