What an assistant can do

An assistant uses Tesria through tools: ten small, named actions, such as “search pages” or “get a page”. You do not call them yourself: you ask in plain words, and the assistant picks the tools and reads the answers. Knowing what the tools are tells you what to ask for.

Every tool works only within what its token’s owner may see and do. A page or space you cannot see answers “not found”, the same as one that does not exist.

Finding things

These work with any token, read-only included.

• list_spaces: the spaces you can see, with their keys, names, descriptions and whether each is public. “What spaces do we have?”

• get_space_tree: a space’s pages, as a tree, leaving out any you cannot see and everything under them. “Show me how the Engineering space is organized.”

• search_pages: full-text search, everywhere or in one space, returning 20 pages (up to 50 if it asks) with the passage that matched. “Find everything about the office move.”

• find_pages_by_label: the pages with a label, everywhere or in one space. “List the pages labeled incident.”

• list_labels: the labels used in a space, most used first, counting only pages you can see. “Which labels does the Docs space use?”

Reading

• get_page: a page as Markdown, with its title, labels, version, address and an outline of its headings. Live content, such as a list of child pages, comes filled in as you would see it. On a long page the assistant can ask for just one section by its heading, which keeps its answers focused. It can also ask for the editor’s own format, to copy a page exactly. “Read the onboarding checklist and tell me what a new starter does on day one.”

Writing

These need a token that is not read-only. With a read-only token they are refused, with a message saying so.

• create_page: a new page in a space, from Markdown, optionally under another page. It is published straight away. “Write a page in the Team space summarizing this meeting.”

• update_page: replaces a page’s content from Markdown, and optionally its title, with a note for the history. Given only a title, it renames the page and leaves the content alone. It replaces the whole page, so a careful assistant reads it first and sends it back with its change. “Fix the typos on the Launch plan page.”

• add_page_label and remove_page_label: a page’s labels. Labels are lower-case letters, digits, dots, dashes and underscores, up to 50 characters. “Label every page about the office move with office-move.”

An assistant can only write to pages and spaces you can edit. A page it writes arrives exactly as your own change would: a new version, watchers told, webhooks sent, and anyone editing the page at the time sees it highlighted to accept or reject. See Connecting an assistant, under When an assistant writes.

What Markdown can say

Assistants write in Markdown, and Tesria turns it into the editor’s elements. These come through as the real thing:

• Headings, paragraphs, bold, italic, strikethrough, inline code and links.

• Bulleted, numbered and task lists.

• Code blocks with their language, quotes, tables, dividers and pictures.

Panels, statuses, layouts, live content and the other rich elements have no Markdown, so an assistant cannot make them. Anything it writes that Tesria does not recognize arrives as plain text rather than being dropped. The idea is that an assistant writes the words and a person adds the finishing touches in the editor. When an assistant rewrites a page that already has panels or layouts, it should read and send the editor’s own format instead, which keeps them.

What it cannot do

There are deliberately no tools for these. Ask a person, or do them yourself in the browser:

• Deleting, restoring or permanently deleting pages.

• Moving pages, and changing permissions or restrictions.

• Creating, archiving or deleting spaces.

• Uploading attachments, comments, and anything in Administration.