Skip to main content

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.

ToolInputsReturns
list-fields (List FieldCraft fields)search and type, both optionalThe 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, optionalThe field types: what each measures, when to choose it, whether it needs acknowledgement, and its recipes
describe-field (Describe a FieldCraft field)fieldWhat 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, issueKeyThe 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 adminsThe 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​

ToolInputsReturns
diagnose-field (Diagnose a FieldCraft field)fieldContexts, 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)NoneThe 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 estimateOnlyAn 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.

ToolInputsReturns
get-field-type-schema (Get a FieldCraft type's configuration options)typeThe type's configuration options, with an example and your site's work calendars and link types
find-recipes (Find FieldCraft recipes)search, optionalRecipes 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 acknowledgeAppAccessWhat 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 acknowledgeAppAccessBefore 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 optionalUp to 100 screens, and whether the field is on each one
plan-add-to-screens (Plan adding a FieldCraft field to screens)field, screensThe 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)fieldThe screens, contexts and work items with a value that the trash affects, and a plan ID
apply-plan (Apply a FieldCraft plan)planIdThe 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:

CodeMeaning
forbiddenYou don't have the permission the tool needs
not-foundThe field or work item doesn't exist, or you can't see it
invalid-inputAn input is missing or wrong
unlicensedFieldCraft's license on the site isn't active
no-callerThe call came without a signed-in person
conflictThe field's configuration changed after the plan was made
failedSomething else went wrong

When the hourly budget runs out, a tool still answers you. It leaves out the fresh calculation and says why.