> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glood.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Every tool an agent can call during a run or a chat: what it answers, what it takes, and when to use it

These are the tools a Glood agent calls while it works, in a scheduled run or in
a chat. Use this page when you write an agent's instructions or a custom skill:
name a tool exactly as it appears here, for example *"Run `get_changelog` for the
hour before the drop"*.

> [!NOTE]
>
> These are not the [AI assistant's tools](https://docs.glood.ai/platform/tools.md). Those are what Claude,
> ChatGPT or another assistant calls through the MCP connector, with your role,
> across the organizations you shared. The tools on this page are what an agent
> calls inside Glood, on the one store its deployment runs on.

## How they are scoped

* **One store.** Every data tool answers for the store the deployment watches.
  No tool takes a store, so an agent cannot read another store.
* **Itself.** Tools that change an agent change the agent making the call: its
  own instructions, schedules, deployments and memory. No tool names another
  agent, and an agent cannot list or read its siblings.
* **Your role, in chat.** In a scheduled run an agent may use every tool. In
  chat it may use only the tools your own role allows, by the permission named
  under each group below.
* **Act is a person's decision.** Setting a deployment to Act, by
  `deploy_agent` or `set_mode`, works only in chat, asked by someone whose role
  has `agent:mode`.

## Budget per run

Each run, and each chat message, has a budget. An agent working through a long
procedure can reach it, so write instructions that fit.

| Limit | Per run or chat message |
| - | - |
| Turns | **12**. With 2 turns left, the agent is told to record its findings and finish |
| Tool calls | **40**, counting every tool except the two below |
| Skill calls (`list_skills`, `read_skill`) | **15**, a separate allowance |
| `record_finding` calls | **10**, a separate allowance |
| Time for one tool call | 10 seconds. `run_checks` gets 60 seconds and `apply_order_actions` 90 |

A run that uses all 12 turns and is still calling tools ends with **Error**,
*"turn budget reached"*. A call past the tool limit is refused with *"tool
budget exhausted"*, and the agent has to answer with what it has.

If a check needs more than one run's worth of reading, split it into two checks,
or ask for fewer, wider queries rather than many narrow ones.

## Store data

In chat these need `analytics:read`, except `list_insights` (`insight:read`) and
the last three (`agent:read`).

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `describe_reports` | The reports this store can answer, what each returns, and which extra input it needs | none | Before `run_report`, unless the exact report name is already known |
| `run_report` | One named report over this store, optionally against a comparison window, with the exact change per column | `report`, `dateGte`, `dateLte`; optional `compare` (none, previous, previousYear, previousYearDow, custom), `compareGte`, `compareLte`, `granularity` (session, user), `model` (session, journey), `collection`, `limit` | For any figure a named report covers. Quote the report, the window and its origin with every number |
| `describe_query` | Every measure and dimension this store's data can answer, what each means, and which may be grouped together | none | Before composing a `query` it is not certain of, and before reporting money |
| `query` | A breakdown no report covers: measures by dimensions, filtered, grouped and bucketed by time | `select`, `since`, `until`; optional `by`, `over` (hour, day, week, month), `where`, `having`, `orderBy`, `limit` (up to 500, default 50), `compare` (none, previousPeriod, previousYear, previousYearDow), `includeBots` | For a question a notch off a named report. The [query-language skill](https://docs.glood.ai/platform/skills-library/query-language.md) teaches it |
| `get_changelog` | What the merchant changed on the store in a window: prices, stock, product status, collections, discounts, themes and market settings. Dense bursts come back as one episode | `since`, `until` (ISO 8601 with an offset); optional `kind`, `subjectType`, `subjectId`, `field`, `limit` (up to 200) | After pinning a metric break to a window, to find what could have caused it. It is the only record of changes made in the store |
| `list_insights` | What Glood's checks found about this store, with each insight's evidence figures | optional `status`, `severity`, `category`, `limit` (up to 50) | Before working out a condition itself, so it does not file a second record of an insight that already exists |
| `get_store` | The store's name, domain, platform, status and time zone | none | To know which time zone query buckets are in. Change-log times are UTC |
| `get_product` | One product's title, handle, vendor, type, status, whether it is in stock, and its price range | `productId` | To name a product a report or change refers to. In stock is yes or no, not a quantity |
| `list_integrations` | What the organization has connected, and the health of each connection | none | To reason about what data exists, for example to say Slack is not connected |

## Orders and fraud

In chat, `run_checks`, `apply_order_actions` and `revert_changes` need
`agent:write`; `list_changes` needs `agent:read`.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `run_checks` | A fraud and delivery risk assessment, by fixed rules rather than judgment: per order, its risk level, verdicts (RTO, returns, prank order, chargeback, stolen card, post-delivery fraud and more), reasons, and the actions the default policy calls for in this mode. With `discount` or `carrier`, one assessment per discount code or courier and pincode | `resource` (order, discount, carrier); optional `orderId` (an order id or the number a person uses, like #1009), `hours` (1 to 168, default 1), `page` | On each new order, return or refund, and once a day for discounts and couriers. Act on its verdicts as the [fraud-policy skill](https://docs.glood.ai/platform/skills-library/fraud-policy.md) says; never re-derive one. 25 orders a page; call again while more remain |
| `apply_order_actions` | Tags orders in Shopify and adds Shopify risk assessments, citing the `run_checks` assessment for each. Returns what happened per order | `orders`: 1 to 25, each `orderId`, `assessmentId`, optional `tags`, `riskLevel` (medium, high), `facts` | **Act mode only.** After `run_checks`, on the orders its policy flags. Every write is listed on the store's Changes tab |
| `list_changes` | What this deployment changed in Shopify, newest first, with each change's status | optional `runId`, `orderId`, `status`, `from`, `to`, `page` | To answer "what did you change" or find a change to undo |
| `revert_changes` | Undoes changes: tags it added are removed, a risk assessment is answered with a new one at no risk | exactly one of `changeId`, `runId`, `assessmentId`, `orderId`, or `from` and `to`; optional `reason` | When a person asks to undo something. It only asks: the revert happens moments later |

## Findings, runs and memory

In chat, `record_finding` and `memory_write` need `agent:write`; the rest need
`agent:read`.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `record_finding` | Records that a watched condition is true now, with evidence. The same fingerprint while the finding is open adds to it instead of duplicating it | `fingerprint`, `title`, `because`, `severity` (critical, warning, info); optional `recommend`, `impactMinor`, `evidence` (`insightIds`, `facts`, `ruledOut`) | Once per cause. Keep the fingerprint stable across runs, with no dates or figures in it. A finding raises its own alert; the agent never announces one itself |
| `list_findings` | This deployment's findings, most recently active first: titles and counts | optional `state` (open, applied, dismissed, resolved), `limit` (up to 50) | To find finding ids. Never conclude there are none without calling it |
| `get_finding` | One finding: what was found, its evidence, severity, state and how often it recurred | `findingId` | To read the evidence behind a finding from `list_findings` |
| `list_runs` | This deployment's recent runs: what woke each, what happened, and how many findings each raised | optional `limit` (up to 50) | To answer "what happened last night". It hands out run ids |
| `get_run` | One past run: status, when, what started it and what it raised | `runId` | To answer about a past run from its record, never by working the numbers out again |
| `memory_search` | What the agent currently believes, agent-wide and for this store | `query`; optional `limit` (up to 50) | Before relying on something it was told earlier |
| `memory_write` | Records something durable it learned or was told | `content`, `scope` (agent: true wherever it runs; instance: true of this store only), `because` | When a person tells it something to remember, or it learns a lasting fact about the store |

## Skills

In chat, `list_skills` and `read_skill` need `agent:read`, `list_org_skills`
needs `skill:read`, `attach_skill` and `detach_skill` need `skill:attach`, and
`author_skill` needs `skill:write`.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `list_skills` | The skills attached to this agent for this store: each slug and its **Use when** line | none | Before acting on anything specific to the organization |
| `read_skill` | The full text of one to five skills | `slugs` (1 to 5) | When a skill's **Use when** matches. A loaded skill outranks the agent's general knowledge |
| `list_org_skills` | Every skill in the organization's library, Glood's and your own | none | To find a skill that is not attached yet |
| `attach_skill` | Gives this agent a skill, on every store or on one deployment | `slug`; optional `instanceId` | When asked to start using a skill |
| `detach_skill` | Takes a skill away, or switches it off on one deployment only | `slug`; optional `instanceId`, `suppress` | When asked to stop using a skill |
| `author_skill` | Writes or revises one of the organization's own skills. Glood's skills cannot be edited this way, only copied | `slug`, `body` (up to 32,768 characters); `title` and `useWhen` for a new skill | When asked to write down a procedure |

## The agent itself

In chat, reads need `agent:read` and changes need `agent:write`.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `get_agent` | The agent in full: instructions, the version in force, its settings, every deployment and every schedule | none | Before proposing any change to itself |
| `edit_instructions` | Replaces its instructions as a new version. Earlier versions stay readable | `instructions` (up to 20,000 characters) | When asked to change what it does |
| `update_agent` | Changes its name, model or default mode. Not versioned | optional `name`, `model`, `defaultMode` (observe, recommend, act) | When asked to rename it. Use `edit_instructions` for what it does |
| `configure_agent` | Changes its Rules, section by section. Only agents with Rules, the Fraud agent today | `config` | When asked to change a threshold, block list or allowed tag. Read the current settings with `get_agent` first |
| `list_versions` | Every version of its instructions: number, when, how and by whom | none | To find the version to roll back to |
| `get_version` | The instructions one version carried | `version` | Before rolling back, so the change can be described |
| `rollback_version` | Puts an earlier version's instructions back, as a new version | `version` | When asked to undo an instructions change |
| `list_schedules` | Its checks: key, name, cron or event, and whether each is on | none | Before adding or changing a check |
| `put_schedule` | Creates or replaces a check, on a cron (in each store's time zone) or an event such as `order.created`, never both. An event check may add conditions the event must match | `key`, `label`, `instructions`, and `cron` or `onEvent`; optional `eventTriggerRule` | When asked to add or change a check, including event triggers the dashboard cannot set |
| `remove_schedule` | Switches a check off on every deployment. The check is kept | `key` | When asked to stop a check |

## Deployments, runs and memory

In chat, reads need `agent:read`, `list_connections` needs `integration:read`,
`set_mode` needs `agent:mode`, and the other changes need `agent:write`.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `list_deployments` | Where it runs: deployment id, store, mode, status and last run | none | To find a deployment id |
| `get_deployment` | One deployment in full: mode, status, who paused it and when, missing integrations and recent runs | `instanceId` | Before changing a deployment |
| `deploy_agent` | Starts it on a store, with its schedules | `storeId`; optional `mode` (default recommend) | When asked to run on another store. Find the store with `list_stores` |
| `set_mode` | Sets how far one deployment may go: observe, recommend or act | `instanceId`, `mode` | When asked to change a deployment's mode. Act needs a person with `agent:mode` |
| `pause_deployment` | Pauses one deployment: its schedules stop until resumed | `instanceId`, `reason` | When asked to stop on one store for now |
| `resume_deployment` | Resumes a paused deployment | `instanceId` | When asked to start again |
| `stop_deployment` | Takes a deployment out of service for good. Its history is kept | `instanceId`, `reason` | When asked to stop on a store permanently |
| `run_now` | Starts a run on one deployment immediately, optionally with a task for that run | `instanceId`; optional `task` | When asked to do something now rather than at the next check |
| `cancel_run` | Stops a run in progress at its next turn. What it already recorded stays | `runId` | When asked to stop a run |
| `list_memory` | What it believes about one store, with who wrote each entry and when | `instanceId`; optional `query` | To review what it remembers |
| `forget_memory` | Retires one belief, with a reason. The entry stays readable | `memoryId`, `reason` | When told something it remembers is wrong |
| `list_connections` | Which connected accounts one deployment may use, and whether each is on | `instanceId` | Before switching a connection |
| `toggle_connection` | Turns one connected account on or off for one deployment | `instanceId`, `connectionId`, `enabled` | When asked to stop or start reading an account on a store |

## The organization

Read only. In chat each needs the permission named.

| Tool | What it answers | Inputs | When to use it |
| - | - | - | - |
| `list_stores` | The organization's stores: id, name, domain, platform and status (`store:read`) | none | To find a store id for `deploy_agent` |
| `list_members` | Who is in the organization, their role, and whether they are active (`member:read`) | none | To answer who could act on something |
| `list_roles` | The roles and what each may do (`role:read`) | none | Before suggesting who should hold what |
| `list_org_connections` | Every account the organization has connected, with its health (`integration:read`) | none | To see what is connected across the organization |

No tool returns credentials, and no tool can invite people, create roles or
change integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.