AI assistant tools
This page lists the 16 tools that FieldCraft gives AI assistants, who can use each one, what it needs and what it returns.
You don't call the tools yourself.
Your assistant picks them from what you ask, and fills in the inputs.
Each tool has a name, such as list-fields, and a title, such as List FieldCraft fields.
AI clients show one or both.
Tools for everyoneβ
Anyone who signs in can use these tools.
The tools that read a work item first check that you can browse it.
| Tool | Inputs | Returns |
|---|---|---|
list-fields (List FieldCraft fields) | search and type, both optional | The FieldCraft fields with their ID, type, value type and a JQL tip. When 25 or fewer fields match, Jira admins also get contexts, screens, acknowledgement and reindex state |
list-field-types (List FieldCraft field types) | search, optional | The field types: what each measures, when to choose it, whether it needs acknowledgement, and its recipes |
describe-field (Describe a FieldCraft field) | field | What the field calculates, in plain sentences, with a JQL tip. Others get the configuration for all spaces. Jira admins get every context, its spaces and the stored configuration |
explain-value (Explain a FieldCraft value) | field, issueKey | The stored value, the configuration in words, when and why it was calculated, any failure or wait, and a fresh calculation. It writes nothing |
preview-value (Preview a FieldCraft value) | field, issueKey, and configuration for Jira admins | The value calculated now, the stored value, and whether they differ. Only Jira admins can pass a draft configuration. It writes nothing |
Value statesβ
explain-value also returns a state: current, counting, out of date, failed, pending, waiting for acknowledgement, not applicable, or never calculated.
For fields calculated with the app's access, only Jira admins get the step-by-step details of the fresh calculation.
Tools for Jira adminsβ
These tools need the Administer Jira global permission.
Check and fill in valuesβ
| Tool | Inputs | Returns |
|---|---|---|
diagnose-field (Diagnose a FieldCraft field) | field | Contexts, the screens the field is on, work items with and without a value, reindexes, suggested updates, up to 10 recent refresh failures, settings and this hour's budget, with findings |
get-backfill-status (Get FieldCraft backfill status) | None | The running, queued and last reindex, with progress and up to 10 failed work items |
start-backfill (Start a FieldCraft backfill) | fields (up to 20), and optional jql, onlyEmpty and estimateOnly | An estimate in work items and hours. It starts a reindex unless estimateOnly is true |
start-backfill uses created >= -90d OR statusCategory != Done when you give no JQL.
It fills in only empty values unless onlyEmpty is false.
Plan changesβ
Each plan tool describes what would happen and returns a plan ID.
Nothing changes until apply-plan runs.
| Tool | Inputs | Returns |
|---|---|---|
get-field-type-schema (Get a FieldCraft type's configuration options) | type | The type's configuration options, with an example and your site's work calendars and link types |
find-recipes (Find FieldCraft recipes) | search, optional | Recipes with their statuses matched to your workflows, and what your site lacks for each |
plan-new-field (Plan a new FieldCraft field) | name, and a recipe with optional slots and workCalendar, or a type and configuration. Optional description, screens and acknowledgeAppAccess | What the field does, its screens, a preview, a warning if the name is taken, and a plan ID |
plan-field-change (Plan a FieldCraft field change) | field, and optional context, configuration, name, description and acknowledgeAppAccess | Before and after in words, a preview on up to 3 work items, a reindex estimate, a plan ID and when it expires |
list-screens (List Jira screens for FieldCraft) | project, search and field, all optional | Up to 100 screens, and whether the field is on each one |
plan-add-to-screens (Plan adding a FieldCraft field to screens) | field, screens | The screens to add the field to, on their first tab, the ones it's already on, and a plan ID |
plan-trash-field (Plan trashing a FieldCraft field) | field | The screens, contexts and work items with a value that the trash affects, and a plan ID |
apply-plan (Apply a FieldCraft plan) | planId | The steps done or failed, and what to do next |
A plan works once, only for the admin who made it, and for 15 minutes.
acknowledgeAppAccess counts only when it's exactly true, after you accept the warning the plan quotes.
A new field applies to all spaces and work types.
A trashed field stays in Jira's Deleted fields for 60 days.
Errorsβ
When a tool can't answer, it returns one of these codes with a message:
| Code | Meaning |
|---|---|
forbidden | You don't have the permission the tool needs |
not-found | The field or work item doesn't exist, or you can't see it |
invalid-input | An input is missing or wrong |
unlicensed | FieldCraft's license on the site isn't active |
no-caller | The call came without a signed-in person |
conflict | The field's configuration changed after the plan was made |
failed | Something else went wrong |
When the hourly budget runs out, a tool still answers you. It leaves out the fresh calculation and says why.
Relatedβ
-
Use FieldCraft with AI assistants: what you can ask, and how a change goes from plan to apply.
-
Connect Rovo, Claude or ChatGPT: turn the tools on and sign in.
-
Hourly calculation budget: what fresh calculations count against.