Skip to main content

🧰 Tool Reference

A tool is one action an AI assistant can ask Swift Axis to perform, such as listing stories or publishing one. This page will guide you through the tools grouped by what they do, with the scope each needs. Your client lists the tools itself, and each tool's description repeats its scope.

Stories are addressed by id, by topic/slug, and a topic by its slug. Inputs use snake_case, such as dry_run and scheduled_at, and results use camelCase, such as dryRun and statusAfter. Image credits use the same keys in both directions, so a credit can be passed on unchanged.

Reading​

All need the read scope.

  • list_topics: topics, with status, story count and order.
  • list_stories: stories without their bodies, filtered by topic, status, kind (story, topic or any), tag or search, with limit from 1 to 100 and offset. Dated entries include their covers date.
  • find_image_alt_issues: stories and topics of any status that have an inline image with no alt text, or an alt text that is only a number with two decimals such as 1.00 (a resize ratio an older Studio editor wrote over the real text). Each result lists the story and the offending images, with limit from 1 to 100 and offset. Fix them with update_story.
  • get_story: one story or topic with its body, status, teaser, tags, writer, image and credit (with the size and smaller versions of its uploaded images), its choices and the choices of other stories that lead to it.
  • get_map: a topic's stories nested by parent, with status and choices, drafts and planned stories included.
  • list_tags and list_authors: tags, and writers with a flag showing AI personas.
  • list_crossroad_targets: the stories a crossroad from a given story may lead to, and why any cannot be linked.
  • search_images: free image search, the same as the Studio's picker.
  • rebuild_status: the rebuild state, the next rebuild time, why it is scheduled, the number of pending changes and the last build result.

Drafting​

All need write:content, and none ever publishes.

  • create_story: create a topic, or a story under a parent or a topic's opening page as a new choice. Status is idea, placeholder or draft (the default). Titles are limited to 300 characters and bodies to 100,000.
  • update_story: change the title, slug, body, teaser, excerpt, tags, writer, image, alt text, credit, featured flag or order.
  • set_choices: set up to three choices on a story, as children or crossroads, with labels, and reorder them.
  • move_story: move a story and everything below it to a new parent or topic. Moving a live story to another topic also needs publish.
  • import_image: store a copy of an image, from a search result or a web address. Unsplash photos are hotlinked (a backup copy is kept, used only if the original stops loading).
  • refresh_link_previews: refetch the bookmark card previews for a story's bare links. If a refetch fails for a link that already had a card, the old card is kept and the result says so.
  • manage_authors: list, create and update writers. Changing who may write as a writer also needs settings.
  • manage_tags: create, rename or delete tags. Deleting also needs publish.

Publishing​

All need publish.

  • publish_story: publish now, or schedule with scheduled_at. Ideas and planned stories are refused, and a story with no topic is refused.
  • publish_thread: publish a topic and its draft stories in order, in one step.
  • unpublish_story: send a story back to draft. A story that other stories link to needs confirm: true.
  • delete_story: delete a story. A real delete needs dry_run: false and confirm: true, and a linked story also needs force: true.

Site and settings​

All need settings.

  • get_settings and update_settings: read and change site settings.
  • trigger_rebuild: rebuild the site now.
  • export_content and import_content: export stories, or import a zip or loose files. An import that publishes also needs publish.
  • list_messages and mark_message: read the contact inbox and mark messages as read, unread or archived.

Pages​

All need admin:pages and an owner.

  • list_pages, get_page: read the site's standalone pages.
  • create_page, update_page: write a page. A new page is always a draft.
  • publish_page, unpublish_page, delete_page: control whether a page is live, or delete it.

The privacy policy is not one of these pages. It is built into the site.

What a result looks like​

Every tool that changes something returns the same envelope: dryRun, blocked, warnings and a plain-English summary, plus fields specific to the tool such as changes or impact. blocked is empty when the change can go ahead. See Good practice for how to use dry runs.

note

Out-of-range values are refused with a readable message rather than quietly changed. For example, a limit above 100 is an error.