A
licenseB
qualityB
maintenanceCaptures and retrieves Markdown records for a personal recording system, enabling journaling, input tracking, search, and date-range review.
4
1
MIT
Tisty
by rgdevment
Tisty's MCP server lets an assistant file and work tasks, write and maintain Markdown documents, and read the store — all locally, with the person keeping the final word.
File tasks —
proposeone or several at once, with date, deadline, list, tags, priority, steps, reminders, parts and source;rescheduledays of agent-filed tasks.Work a task —
plansteps,tick/untickthem,reword_step,unplan,moveit into a list or under a part,renameagent-filed titles,describethe description,note/reword_notein the journal.Report outcomes —
say_doneorsay_not_doing(marks for the person to confirm; never closes anything),reminda task to ring.Read tasks —
reada whole task or selected fields,findacross open tasks, the archive and documents by words, dates, tags, list, source or agent flags.Write documents —
write_docnew or whole,append_docat the end/under a heading or to a task's page,edit_docone passage,edit_tablecells/rows/columns,restore_docto undo a write,import_docfrom Markdown files on disk.Read documents —
docslists them with folders, size and gist;read_docbody or part with aprint;outline_docheadings, pages, dead links and duplication signs;sum_upleaves a private summary for the next agent.Organise —
foldercreates folders,file_docfiles documents,page_dochangs documents as pages and orders them,archive_docputs away/restores,flag_docmarks a document for the person to delete,export_doccopies one out to disk.Attach files —
attacha file from disk to a task or into a document (rendered as picture, card or sealed HTML widget).Orient and learn the rules —
catch_upfor the state of the store plus a cursor of what moved,lists,tags,rules,languageandhelpfor conventions and Tisty's own docs.Guardrails — no closing or deleting tasks, no deleting documents, no AI or network use; the person opens each assistant and approves what it says is finished.
Tisty is open source: read it, build it, run it, or take one of the signed releases already out there. Nothing is hidden and all of it can be audited.
It is a place to write. Documents are Markdown files on your own disk that hold far more than text: a book in pages, diagrams drawn from a few lines, formulas, code named after its file, small widgets, pictures and PDFs that travel with them, and a PDF of their own when you print. Search reads them with the tasks, and an assistant can read and write them too.
It is not a to-do app as you know it. A list gets emptied and forgotten. Here what you close stays: what you did, when, and what you worked out on the way. Months later you search for how you solved something and it is there — the description, the journal, the steps, the documents you leaned on.
I am not a company. I am a developer who kept solving the same problem twice, so I built the notes, documents and task manager I wanted and gave it away. It is meant to stay small and useful, not to grow a thousand features nobody uses. No ads, no telemetry, no accounts, no subscriptions — a local-first productivity tool that lives on your machine and nowhere else.
Why people choose Tisty over other task managers:
100% local — your tasks, your journal and your documents live on your computer and go only where you send them. No server of ours, no account. If you sync two machines, you can ask Tisty to leave the largest attachments in that shared folder instead of carrying them onto every disk; it never does that unless you choose it.
Documents that do more than text — books in pages, diagrams, formulas, code, widgets and attachments, all of it plain Markdown any other editor still opens.
Truly free — no premium tier, no feature gates, no trial. AGPL v3.
Your data outlives the app — plain text and Markdown on your own disk, readable with
catand searchable withgrep.Finishing keeps everything — completing a task moves it to the archive with its steps, its notes and its attachments intact, documents included.
Fast and native — a Rust core inside a Tauri window: it starts quickly, stays small, and looks like it belongs on both systems.
I use Tisty every day on macOS and Windows. If something feels off, open an issue — this project keeps improving because of real-world use.
It is for one person, by design. No assignees, no permissions, no boards. If you need to run a team, Tisty will not carry that.
Table of Contents
Related MCP server: Noted
Why I Built This
Organising your day is harder than a list makes it look. There are more moving parts than fit in your head, plans shift under you, and something you thought was small turns out not to be. Which is why finishing it feels good.
But look at what the task gathered on the way. The steps it actually took. The notes you wrote while working it out. What you looked up, what it turned out to connect to, the documents you leaned on. That is where the effort went.
Mine looked like "fix the intermittent timeouts on save". By the time it was done it had collected the ticket, the commit, and two paragraphs explaining that the real cause was a missing index on a table nobody was looking at.
Eight months later the same thing happened somewhere else. I remembered solving it. I could not remember how — and the note that held the answer had gone with the tick.
That is the whole reason Tisty exists. A task is not a line you cross out. It is a tree: the steps, the journal, the files and the documents that grew around it while you worked. Finishing it should not prune it.
I wanted it to stay mine, too. On my disk, in files I can open without asking anyone. So I built the thing I wanted, used it until it stopped annoying me, and put it here in case it is the thing you wanted too.
What It Is / What It Isn't
It is a personal task manager where finishing something is the beginning of its useful life. Tasks carry a description, a journal, steps and attachments; when you complete one it moves to the archive, and search reaches all of it, documents included.
It is a place to write, too. Documents are not a notes field bolted onto the tasks: they are Markdown files that grow into books, with diagrams, formulas, code and their own PDF.
A task or a document? A task is something to do: it ends, often soon, and then it stays, so that months later you can look up how you solved it. A document is something to keep and read again — a manual, a recipe, the notes on a client — that grows and lasts for years. Something you will do is a task; something you will come back to is a document. A spike is the clearest case: a task whose page gathers what you found out — notes, recordings, code analysis — split into parts that each get done, then completed and archived — and a year later a search still brings back how it was solved, every step of it. That is why a task has a page: it is also a document, one with an end.
flowchart TD
A[Something comes up] --> B{Will you do it,<br/>or come back to read it?}
B -->|Do it| T[A task]
B -->|Read it again| D[A document]
T --> P[Its page: notes, steps,<br/>files, recordings]
P --> S{Too big for one go?}
S -->|Yes| K[Split it into parts]
K --> C
S -->|No| C[Complete it]
C --> R[The archive:<br/>search finds how you solved it]
P -.->|You learned something<br/>you will need again| D
D --> G[Read, correct and add to it<br/>for years]It is for one person. No assignees, no permissions, no boards. If you need to run a team, Tisty will not carry that, and you deserve to know before you install it rather than after.
It is not something I sell. Nothing is locked, nothing expires, and there is no version of this with more in it. It is a program I wrote for myself and gave away.
Your data is files. Plain text on your own disk, readable with cat and
searchable with grep. If Tisty disappeared tomorrow, everything you wrote
would still be there and still make sense.
What Makes It Different
If you are looking for a free, open-source, offline place for your documents and tasks, with no account, no subscription and no AI, this is what Tisty is:
Your tasks live | in plain files on your own disk |
Account | none, ever |
Subscription | none. There is no paid tier and no upgrade |
Offline | always. There is no server to be away from |
AI inside | none, and none is coming |
Your own assistant | yes, over MCP, if you choose to open the door |
Priorities | the Eisenhower matrix, by its name |
Sorting | lists, tags, steps and a journal on every task |
Documents | Markdown files with pages, diagrams, formulas, code, widgets and their own PDF |
A document with pages | a book, with its chapters in the order the text names them and an index |
Diagrams and formulas | drawn from a few lines of text, light or dark with the window |
Widgets | small pages of HTML in Tisty's colours, sealed off from the network |
its own: A4, Letter or Folio, with its pictures inside | |
Any | opens to read in a window of its own, without coming into your store |
Attachments | kept with the task, as themselves |
Finished work | an archive that keeps what each task taught you |
Two machines | your Google Drive, OneDrive or WebDAV server, reached directly, or a folder you already sync. No server of ours |
Your cloud, encrypted | if you want it, with a 24-word phrase only you know |
Natural language | dates, deadlines and repeats, parsed on your machine |
When to do it | a spread of days you deal work onto, and a month for looking |
Reminders | an hour you choose, that rings on this machine and nowhere else |
Source | open, auditable, yours to fork |
Documents that grow into books. Most task managers give you a notes field.
Here a document is a file of its own, written on a lit page, that holds pages
like chapters, draws the diagram you describe, sets the formula, colours the code
and makes its own PDF — and it stays Markdown that GitHub, any editor or cat
read the same. A task can point at it, and search finds both.
The Eisenhower matrix, not numbered priorities. A task is urgent, important, both or neither — do, decide, delegate, drop. That names the decision instead of hiding it behind a number, and it is the difference between a list that sorts and a list that helps you choose. Around it: lists for where work belongs, tags for what cuts across, steps for the parts, and a journal for what you learn on the way.
Finishing is where it starts. Most task managers treat a completed task as rubbish to hide. Here it moves to an archive read in three layers: the ones that taught something come with their whole trail — what changed, when, and what you wrote — the routines come with their tallies and their streaks, and the rest is the trace. Search reaches all of it, documents included. A year in, that archive is the part you would miss.
Your assistant, not one of ours. Tisty has no AI in it. The natural language that turns "call the bank at 3" into a task is rules running on your machine, no model and no cloud. But it speaks MCP, so an assistant you already use can file work into it — with its steps, its date and the list it belongs in, on this machine, with no account and nothing over the network. You open that door, and you can close it.
Two machines, no middleman. Tisty talks straight to your own Google Drive, OneDrive or WebDAV server, or travels through a folder you already sync. There is no server of ours in between, nothing to sign up for, and nothing that stops working the day a company changes its mind. And what it keeps in that cloud can be encrypted with a phrase only you know.
Free is not a tier here. There is no upgrade, no seat count, no feature held back for later. The reason is not generosity: a program that keeps your work on your disk and never phones home has almost nothing to charge for, and asking would make it worse.
Documents
The other half of Tisty, and for many people the larger one. A document is a Markdown file on your own disk — the same file any other editor opens — and in Tisty it holds a good deal more than text:
A book in pages. A year of minutes, a manual by chapters, a dog's life told year by year: one document holding its pages, in the order the text names them, with an index at the end and arrows from one to the next.
One document in several languages. Each language is a file of its own, and Tisty shows them as one row, opened in the app's language, with a switch that takes you to another language at the same section. Moving, archiving and deleting act on every language at once.
Diagrams from a few lines. A block that says
mermaiddraws flowcharts, sequences, pies, timelines, mind maps, Gantt charts and more with the official Mermaid, light or dark with the window and legible at any width. A double click opens it in a window of its own, where a mind map, a database schema, a freeform diagram or a class diagram is also drawn by hand, with a palette of every Mermaid shape, saved back as Mermaid, drawn on the page as in the window and exported as PNG, JPG or SVG.Formulas set from a
mathblock, code coloured by its language and named after its file, and tables that keep how their columns lean and how wide you drew them, whose columns can say what they hold — money, dates, choices, ratings, yes or no — and add themselves up at the foot, written on the page cell by cell.Widgets: a small page of HTML, styles and a little script, drawn in Tisty's colours and sealed off from the network.
Callouts, highlights and icons — the callouts GitHub reads, pens in several colours, an icon looked up by what it draws — and boxes you tick.
Attachments that travel with it: pictures, PDFs, sound and film, kept inside Tisty rather than linked to a folder that moves. A click on a picture or a diagram opens it large, to zoom in and go to the next one.
A PDF of its own, A4, Letter or Folio, with its pictures inside, shown to you before you export it.
The guide Tisty writes the first time it opens carries a page with one of each, so you can see all of it before you write a line.
Documents live beside the tasks, for reference material that has no date and never gets ticked. They are Markdown files you edit as documents — tables, checklists, code, images — and search reads them too. A task can point at a document; a document never creates tasks.
The tree opens quiet and closes whole. Every folder starts folded, so a store with hundreds of documents is a handful of rows until you go looking. When work is over you archive the folder itself, not its documents one by one: it drops to the shelf at the foot of the tree with its icon, its subfolders and its pages exactly as you left them, closed to writing and to anything new coming in. Bring it back and it returns the same — including whichever documents you had archived by hand in there, which stay archived because nobody said otherwise.
A page is put away on its own without leaving its document. A long thing in parts — a year of minutes, a book by chapters — is one document holding pages, and a chapter that no longer applies goes to the archive where it lives: dimmed, with the icon of the archive, read but not written. Put the whole document away and every page goes with it; bring it back and each one returns as it was, the one you had set apart still apart.
A document takes tags the way a task does — you write #contract in the
middle of a sentence and the document is filed under it. The tag lives in the
sentence rather than in a hidden header, so carrying the file to another editor
carries the tag with it. Tags is where they meet: one screen, the tasks under a
tag and the documents beneath them, and pressing a tag inside a document opens
exactly that. Accents come off and case is folded, so #camion and #camión
are one word however you typed them that day. A bare number is not a tag —
#1234 is the ticket somebody wrote down, not a subject — and neither is a
single letter: two characters, one of them a letter.
Text can be highlighted in a few colours and set apart as an aside — a plain
quote, or a callout GitHub reads too, written as > [!WARNING]. Tables keep how
their columns lean and how wide you drew them, and a column can carry its type
in braces at the end of its head, Price {money USD sum}: Tisty shows, sorts and
adds up its cells as that, while the file stays a table any reader opens. A code
block says what language it is and is coloured for it, with its lines numbered
beside the text rather than in it, so copying takes the code and nothing else.
A block can carry a name; one whose language is mermaid draws the diagram it
describes
underneath — redrawn when you turn the light on or off — and one that says
math sets the formula it holds. One that says widget is drawn as a small
page — HTML, styles and a little script if you like — sealed off from the
network and from the window, and an .html file attached to a document is drawn
the same way.
A web link on a line of its own is drawn as a card, made from the address itself — the site's name and the words you wrote. Nothing is fetched to draw it. Press Bring the preview and Tisty asks that page once for its title, its description and the picture it offers, keeps the answer here so it never asks again, and reads no more of it than it needs: a page cannot decide how much of your machine it takes.
It stays Markdown, and that is the point rather than a detail: everything
above is syntax another reader already understands, so the file survives without
Tisty — a block's name is what Markdown keeps after the language, and a column's
width rides in how long its rule is drawn, which every other reader ignores and
draws the same. Where Markdown has no word for a thing, Tisty adds a few short
ones of its own, never HTML: ==words== is a highlight and ==words=={green}
one in another colour, ++words++ is underlined, ::star:: is an icon, and an
attachment is named by its own name, . The editor
shows the file exactly as it is written, a block at a time, so what you see while
writing is what is on disk. Copy as Markdown and taking a document out say
those few words the way any other reader understands them, and an older file, an
import or an assistant writing in plain Markdown is turned into them on the way
in.
The writing sits on a lit page, and the first line with words in it is both the
name of the document and its title — reading past a fence or an alert's marker to
find it. When the window is wide enough a column opens beside it
with what the document is, the formatting the / menu used to hide, and its
outline. Tisty makes its own PDF — A4, Letter or Folio, with its
own margins and its pictures carried inside — and shows it to you before you
export it.
A Markdown file from anywhere opens to read. Pick Tisty under Open with
for a .md file, or follow a tisty://open?path=… link, and it opens
read-only in a window of its own without coming into your store: its contents
at the side, what the file is, the width of the page, and the PDF it would make,
with ← Back to the document. Edit in Tisty brings it in as a document
and leaves the original where it was. A document of yours opens the same way
from its panel, Open in a window of its own, and its PDF there is signed
unless you untick Signed. A widget opens apart too, at phone, tablet or
desktop width. More in the help.
And they leave whole. A document copies as standard Markdown, the way
GitHub and CommonMark read it, writes out into a folder with its pages and
attachments beside it, leaves as one web page or a Word file with its pictures
inside (Markdown to HTML, Markdown to Word), or is exported for Tisty into a
.tistyx file that also carries what Markdown cannot say: folders with their order,
icon and colour, which document each page hangs from, what is archived, and the
alias it was signed with. It carries a README.txt as well, so whoever you hand
it to can read the documents without Tisty and knows where to find it if they
want the rest. Exporting all of them asks who they
are for: open, to hand to somebody, or locked with six digits for another
machine of your own — which is what makes them arrive there as yours rather
than as a stranger's. Either way, not one line of the history travels inside.
Write an alias — optional, and yours to choose — and every document is signed
with it, while whatever arrives from somebody else keeps theirs.
Who Is This For?
Someone who works alone, or mostly alone, and whose tasks leave a trail worth keeping. Developers, sysadmins, freelancers, researchers, students — anyone who has ever solved the same problem twice and known it the second time.
And anyone who writes things that last: a manual, the minutes of a year, notes for a course, the documentation of a system, a book in chapters — and wants it in files of their own rather than in somebody else's database.
If what you want is a list to cross out and never open again, Tisty will feel like more than you asked for. That is a fair reason to walk away.
The Idea It Is Built On
A completed task is not finished. It is archived.
It stops being a reminder of what to do and becomes the record of how something got solved. Three things follow from that, and they shaped everything else:
Search is the main way into the archive, not a side feature.
Deleting is the exception. The normal ending is completing, which keeps it. Erasing something for good is only for what is closed and reads as a trace; a story is only hidden, and converting it to a trace is the deliberate step that lets it go.
Capture has to stay instant, because most tasks are not like that at all. The call you have to make tomorrow is born and dies within a day and leaves nothing worth keeping — and writing it down must not cost more than one line.
A document is a file you keep, not a row in somebody's database. Whatever Tisty draws on top of it — pages, diagrams, widgets, a PDF — the file underneath stays Markdown another reader opens the same, so leaving Tisty never means leaving your writing behind.
Getting Started
Windows — from the Microsoft Store, which keeps it updated for you. About asks the Store for one on the spot when you would rather not wait. Or with the Windows Package Manager, which takes the signed installer from the releases page and then stands aside, because Tisty keeps itself up to date:
> winget install rgdevment.TistymacOS — with Homebrew. The tap is added and trusted once and never again; Homebrew loads a tap that is not its own only once you trust it. After that Tisty keeps itself up to date, so Homebrew stands aside:
$ brew tap rgdevment/tap
$ brew trust rgdevment/tap
$ brew install --cask tistyOr take the disk image and the installer straight from
Releases, on either system.
On macOS there are two images: aarch64 for Apple Silicon and x86_64 for
Intel — Apple menu › About This Mac says which one yours is. Homebrew picks
by itself.
What It Does
The first time it opens, Tisty asks two things — which language, and where your copies should go — and then writes you a guide and opens it, unless the place you chose already holds your Tisty: then it brings that instead. Everything else it decides for you and lets you change later: it starts with the computer and waits out of the way, because those were questions with an obvious answer. The guide is a document in your own store, in a folder of its own: yours to read, edit, or throw away like anything else you wrote.
Settings takes over the sidebar with its sections. General is how Tisty behaves towards you — language, light or dark, start-up, the quick capture, notices, and the one thing that happens outside the window: the welcome. Sync is where your copies go, which computers are yours and where the big attachments live. Security holds your 24-word phrase and the encrypted cloud. Your data is your folder, backups, what you take out or bring in, and a guide that leaves a computer clean if you want Tisty off it. Assistants and Maintenance are what they say, and About comes last: the notice of an update shows only when there is one, and takes you straight there.
Three columns at most: what you are looking at, the list, and the task you opened. Nothing else on screen.
The list stands where it stands. It does not drift to the middle of whatever room is left, so opening a task moves nothing. Where the window is wide enough, the space that opens up is not left blank: a column tells you the day — what is overdue, what is late, what is for today, what is ahead, the four quadrants with their counts, the lists holding something and the tags in use. All of it counts your whole store rather than the slice on screen, and every figure is a way in. Narrow the window and it steps aside; a task always wins the room over it.
It reads what you write. You type a sentence and Tisty takes the date out of it, leaves the sentence readable, and shows you what it understood before anything is saved — as chips you can correct with one click.
"ship the release tomorrow at 10" → tomorrow 10:00
"file the report before friday" → due fri
"book the flights @travel #urgent" → @travel · #urgentA day, a time, or both. Names, distances, plain dates. What it cannot read it leaves alone rather than guess. A deadline is a different thing from a plan, and four words open one: before, by, due, until.
A task opens beside the list, not on top of it: dates, list, tags and priority above, and below them its own page, a Markdown document like any other, with sections to fill in and a grey hint in each. Every box on that page is one of its steps; press ↗ on one and it becomes a part of the task, its card left where the step was. Completing it puts its page away with it, readable and untouched, and reopening brings it back. Opened to the whole page it gains a column of its own trail — how long it has been open, how much of it is done, and every change it has been through.
Priorities are a matrix, not a ladder. Tisty borrows the four quadrants of the Eisenhower matrix — the method President Dwight D. Eisenhower is credited with, popularised by Stephen Covey in The 7 Habits of Highly Effective People: sort what you have by urgent against important, and each quadrant tells you what to do with it. Do what is urgent and important, Schedule what matters and is not urgent, Delegate what is urgent and is not yours, and leave in Minor whatever you could live without — when you are sure, one button drops the lot.
Drag a task into its quadrant, or type it: !do, !schedule, !delegate.
!decide still works, because it is what the quadrant used to be called. Each
quadrant has a + that opens the quick capture with that quadrant already
set, and whatever nobody has placed waits in a tray that opens the way you
left it.
The spread deals your days, one row at a time. Priorities sort what matters; the spread decides when. It runs as a river of days you scroll through rather than a week you page: every day is a row, and the row grows with what it carries, so a heavy Friday is tall and a free Tuesday is a line. What you wrote with no day waits in a tray on the left, and you drag it onto a day — or drag it back to take the day away again. Drop one onto a day that already carries three and Tisty says so, and offers the next day that is free; it never insists.
A month button is there for looking, not for dealing: press it and the same days lay out as a grid, press a day and you land on it in the river. Nothing is dropped there on purpose. Tisty cannot see the calendar you keep somewhere else, so a square with nothing written on it is only a square with nothing written on it — never a promise that the day is yours.
Tisto keeps you company. Tisty's beaver peeks over the bar while you write a task and gives you a thumbs up when you finish one. It never covers anything, and Settings turns it off.
A global shortcut opens a small field over whatever you are doing, so a task that occurs to you mid-something does not cost you the something.
A calendar comes in as tasks. Drop an .ics on the window, or open one with
Tisty: it shows each event and to-do with when, where, how it repeats and its
reminder, and makes the ones you pick into tasks — time zones, Outlook's
included, and simple repeats kept, and a file opened twice brings nothing twice.
Repeating tasks come back one occurrence at a time, so the archive shows you did it twelve times — and it counts what was owed rather than only what you closed, so a routine reads 26 of 30 with four dates that have no record. Marking one days late offers those dates back instead of calling them forgotten: tick the ones you did and the gap closes. Reminders arrive as a system notification and a short sound you can turn off. The whole window works from the keyboard.
The archive is read in three layers. The ones that taught something — a task you came back to and added to more than three times — come with their whole trail: what changed, when, and what you wrote along the way. The routines come with their tallies, their streaks and the hour you usually keep them. The rest is the trace: what left little or nothing written, listed dense and out of the way, because it still happened and search still reaches it. You decide which layer each one reads in: a story that was only noise goes to the trace, and a trace worth keeping is kept as a story. The trace is the only layer that can be erased, and both erasing and hiding are one task at a time; a story is only ever hidden.
Your Data and Privacy
Everything lives in one folder on your disk: an append-only log of what
happened, your documents as .md files, and your attachments as themselves.
Nothing is obfuscated and nothing is in a format only Tisty can read.
Nothing on your disk is encrypted at rest, and that is a decision rather than an oversight — your operating system's permissions are the protection, and the files stay readable with tools you already have. What Tisty keeps in a cloud it reaches directly is another matter: that you can encrypt with a phrase only you know, as the section below tells. Both are written out in PRIVACY.md and SECURITY.md, including the parts that are not reassuring.
Tisty makes one check unasked — when it opens, and once a day after that: it downloads a small file and its signature to see whether a newer version exists. It sends nothing. If one does exist and you press the button that offers it, two more requests follow — the file naming the release, and the installer — and Tisty refuses to install anything not signed with a key compiled into the copy you already have. There are a few more, listed in PRIVACY.md.
Folio by Tisty is a separate service for sharing a document by an anonymous, end-to-end encrypted link, with its own terms and policies in its own repository. Tisty does not share by link, and has no code that talks to it.
Two Machines, If You Have Two
Tell Tisty where to leave the copies, in Settings › Sync. There are two ways — a cloud Tisty talks to directly, or a folder something else keeps in step — and the rest it does on its own.
Your Google Drive, directly. Choose Your cloud service and Connect: your browser opens, you sign in to Google, and Google asks whether Tisty may keep its copies there. They live in a hidden space of your Drive that only Tisty opens — it sees nothing else in your Drive, and they do not show up among your files — and you do not need Google's desktop program installed or running. Disconnecting keeps them there, in Tisty and in Drive alike; to take them out, move to a folder from Tisty. In Google Drive › Settings › Manage apps, only Delete hidden app data deletes them. The first time, everything you already have goes up — or, if your Drive already holds your Tisty, it comes down instead; after that only what is new travels, and a dropped connection carries on where it left off. Attachments stay on the computer they were added on and come down on another one when you open them there; Free up space lets go of the ones you have not opened in a while. Each computer has a daily allowance, so no single copy can spend the quota Google grants the project: when it runs out, what you write stays safe here and syncing carries on the next day. Connecting happens only in the window.
Your OneDrive, directly. The same, with Microsoft: you sign in on Microsoft's page and Tisty keeps its copies in Apps › Tisty in your OneDrive. That folder is one you can see there; leave it to Tisty, since what you change by hand reads as a change from another computer.
Your own server, over WebDAV. Nextcloud, ownCloud, Synology and others: you type the server's address, your user and a password in Settings, and Tisty checks the server before connecting — no browser opens. The password stays on this computer, kept by the system; an app password from your server is better than your main one, since you can remove it there whenever you like. Tisty keeps its copies in a Tisty folder on the server and touches nothing beside it; leave that folder to Tisty too. Your server sets the limit and the pace, and attachments always stay on this computer as well.
Before you connect, and before a move to the cloud, Tisty checks that the provider answers, with one request that carries nothing of yours. If a proxy, a filter at work or an antivirus stands in the way, it says so in plain words — there, and on the card once syncing keeps failing: a second round in a row, or two minutes after the first. A single failed round, or a connection cut halfway, is only tried again. It never goes around what stands in the way: what you write stays here and goes up once the way is clear. A round that runs long says for how long, so it never looks frozen.
A folder. Google Drive, OneDrive, iCloud and Dropbox's own folders — whichever it finds installed, folder already worked out — or any other folder both computers reach, a NAS, a drive you plug in on Fridays. Dropbox travels this way, through its own program.
There is nothing of mine in the middle: no account, no server, no daemon. Who runs that folder or that cloud is your business, not Tisty's. If you sync nothing, it never opens a connection for it at all. Changing your mind later is a move, not a switch: Move to another place… takes your copies between this machine, a folder and your cloud in two steps — first it brings home what lived only in the place you leave, then it takes everything to the new one — counting the files left, says so when the provider asks for a pause, lets you hide it and keep working, and tells your other machines where you went so each one follows.
A new computer joins on its own. If it holds nothing of yours yet, it takes what the folder or your Drive already holds, after keeping a backup — connecting Drive there says Your Google Drive already holds your Tisty and offers Sync instead of a first upload. It brings it with a moving bar and counts as things arrive, and Keep working while it arrives lets you into the app while the round goes on; the foot of the sidebar keeps counting and says if it could not finish. One that does hold your work asks first, naming the place: merge the two, keep this machine, or take what the place has. If your cloud is encrypted, a new computer is let in first, as told below.
Two machines can genuinely write the same document at once, and there Tisty merges them block by block — you edit the introduction on one, someone edits the closing paragraph on the other, and both land with nothing to answer. Only a real overlap becomes a question.
An older Tisty does not write over a newer one. A computer still on Tisty 1.30 to 1.33 that reaches your cloud or your folder stops and asks you to update it instead of carrying on. Until you do, that computer does not sync, but nothing is lost: what it holds stays where it was and catches up once it is updated.
Each machine signs what it writes, and one nobody here has answered for waits at the door: its card in Settings › Sync, under Your computers, shows the code it signs with, you compare it with the one that machine shows for itself, and confirm it. Until then nothing it writes comes in; from then on, whatever does not answer to that key is turned away, and Tisty says so.
Your cloud, encrypted, if you want it. In Settings › Security, Encrypt my cloud… encrypts what Tisty keeps in your Google Drive, your OneDrive or your WebDAV server with a key that comes from a 24-word phrase only you know. Whoever sees those files, your provider included, can no longer read your tasks or documents, and what is on your computers does not change. It is for a cloud Tisty reaches directly; a folder kept in step by another program stays as it is.
Before it starts it checks three things: that your phrase is written down — Save as PDF gives you a sheet to keep, and three of its words confirm you did — that the cloud has room, since it takes twice as much until the old copy goes, and that every one of your computers runs a Tisty that knows an encrypted cloud. Then it shows the progress. You can keep working, close Tisty and have it carry on where it was, or cancel: until the last step, what was there stays as it was. Once it is done the old unencrypted copy stays in the cloud until you press Delete the unencrypted copy, and Decrypt my cloud, in the same place, turns it back to plain; your other computers notice and keep syncing without you doing anything on each one.
Your computers get the key on their own. One that already synced with you waits a moment and takes the key from another of yours that has Tisty open, and meanwhile it writes nothing unencrypted. A new computer is let in from one that already reads the encrypted cloud: on the new one, Let in from another computer shows twenty digits, and you type them on the other under Settings › Security › Let a new computer in; then It took them on the new one says you did. Or type your 24 words on the new one with Type my phrase: only the cloud's key stays there, never the phrase. Whichever history you then keep, the computer that took the twenty digits does not ask for it again; each of your other computers asks you to confirm its code once, as with any new computer, since the key alone does not say which computer is yours.
What it does not hide. Your provider keeps earlier unencrypted versions for a while, in its history and its bin, and the names and sizes of the files and how many computers you have stay visible. The phrase never passes through anybody's hands, so nobody can give it back to you: without it or one of your computers, nobody can open your cloud, not even us.
And back up by hand, shared folder or not. One zip with your whole history, kept wherever you like, and restored from the same place in Your data.
Where the big ones live is yours to say. By default every machine carries every attachment, which is why any of them can open anything with the network off. For anything above 25 MB, Settings offers two other ways: keep only what this machine attached and fetch the rest when you open it, or leave them in the shared folder and nowhere else. That last one trades the copy on your disk for the space it took: the file is there when your provider or your NAS is, and Tisty says so plainly when it is not. A copy is only ever let go of after the one in the shared folder is found to hash the same.
And because what uploads a folder is your provider's program and not Tisty, if you ever change something on one machine and it does not turn up on the other, the help lists the causes worth checking, in order — and what each message about Google Drive means, from Reconnect to a full Drive or something blocking the way.
An Assistant, If You Use One
Tisty is not AI and has none inside. The natural language that turns "call the bank at 3" into a task is rules running on your machine: no model, no request, no cloud. That is not going to change.
But if you already use an assistant, you are probably telling it things worth keeping — the school group says card stock on Monday, the invoice is due on the 30th. So Tisty leaves a door, and you decide whether to use it.
Your agents' work, in the open. Through Tisty, an agent plans in documents and works in tasks: it writes the plan, what it found and what it decided as Markdown, breaks the work into tasks with steps and ticks them off as it goes. Nothing stays buried in a chat: every stage lands in Tisty, on your computer, where you can follow it as it happens and audit it later. When it says a task is done, you are the one who closes it.
Settings › Assistants lists the assistants already installed on this computer and
connects the one you pick: it writes a single line into that assistant's own
settings, leaves the rest of that file where it was, and keeps a copy of it as
it was before. For one it does not know, a line does it, and the tab shows it
with where the tisty that came with the app sits on this computer:
$ <your-assistant> mcp add tisty -- <path-to-tisty> mcpWhere <your-assistant> is whatever yours is called. That tisty is not a
command line any more: it opens only the assistant's door. It speaks
MCP on the same machine: no
account, no token, nothing over the network. You are the one who opens it.
The assistant appears in Settings › Assistants as a device you have to let in, and
it stays a device you can throw out; until you do let it in, everything it
tries is refused.
While assistants have a voice, a stable Tisty also answers to the name tisty
on your PATH — the Store and Homebrew put it there, and the installer's copy
adds its own folder — so a plugin can start it by name. Taking the voice away
takes that folder off the PATH again. Restart an assistant that was already
open so it sees the change.
What it may do is deliberately small: file a task with its steps and its date, set an hour for it to ring at, move the day of a task it filed itself, say that a task it filed is done — which marks it for you to confirm and closes nothing — add to the journal, write a document, add to one that is already there — at the end or under a heading — correct a passage of one, write one again whole, file documents into folders, make one document a page of another and say the order its pages are read in, which writes and moves the lines naming them in your document's text and nothing else, keep a copy of a file you point it at — on a task or inside a document, which takes the larger file of the two — and read what is already there. What it may not do: close a task or delete one, say a task you wrote is done, move a day you set, delete a document, rename or empty a folder, reach a task you folded away, take files from anywhere but Downloads, Documents, Pictures, the desktop and the temporary folder, or file the same thing twice. A task you closed is history to it: it comes with a notice saying so, reads as it ended, takes no note, no new day, no bell and no file, and if the same work comes back the assistant proposes a new one that says how the last one ended.
A task you wrote stays yours unless you say otherwise. Open one to agents from its detail — «Allow agents» — and an assistant may say it is done, or that it should not be done, for you to confirm; describe it, where there is no description yet; plan its steps; and tick them off as it goes, which is the one thing it does without asking — taking back a tick it gave by mistake included, never one you gave. Its day, its title, its list and its closing stay yours all the same. «No agents» shuts the door again and keeps what was filled in. What an assistant writes is signed with the name of the program it spoke through: a row and the side panel say «by an agent» and name it on hover, while the full page and the journal say «by Claude Code», «by Codex». Settings › Assistants counts what each one wrote.
It also reads sparingly, which is your business as much as its own. Tisty keeps a small card for each document — its headings, how long it is, what it leans on — worked out from the text itself, on this machine, and never sent anywhere. An assistant reads that to pick which document it needs, then asks for the part it wants, or changes that part without having read the rest. A long document is not poured into somebody's model because an assistant wanted one paragraph of it. Having read one, it can leave a summary for the next one — kept on this machine, never synced, and not part of what you wrote. To correct a passage it has to name it exactly as you wrote it, and if that text is not there or is there twice, nothing is written at all. To write a whole body again it has to send back the print the document read at when it last looked: if you have written in it since, the write is refused and it has to read again, so what you typed while it was thinking cannot be lost. A document you archived it can still read, and it is told that you archived it.
Whatever it reads travels wherever that assistant travels. That is between you and it — which is precisely why this is a door you open, and not one that was already open.
What It Does Not Do
As important as the list above. Out of scope for now: real-time collaboration, kanban boards, Gantt charts, time tracking, productivity metrics, databases that relate tables across documents, formulas in cells, and AI anywhere in the critical path. A table's columns can say what they hold and add themselves up, but each table lives in its own document.
The natural language stays deterministic and local, and Tisty never sends anything to a model — not a task, not a word. If you open the door in the section above, whatever your assistant reads travels wherever that assistant travels: Tisty still sends nothing, the assistant is the one carrying, and you are the one who let it in.
FAQ
Is Tisty free? Yes, and it stays free. AGPL-3.0, no paid tier, no feature held back for a later version, no trial that runs out.
Does it need an account or a connection? Neither. There is nothing to sign up for and no server to be away from. Tisty makes one network request you did not ask for — when it opens, and once a day after that — to see whether a newer version exists, and it sends nothing in order to ask. Take the machine off the network and everything else works the same.
Where is my data kept?
In one folder on your own disk: an append-only log of what happened, your
documents as .md files, and your attachments as themselves. Settings › Your
data prints the path and Show folder opens it. Nothing is obfuscated and
nothing is in a format only Tisty can read.
What happens to my notes if Tisty disappears?
They stay where they are. Markdown and plain text, readable with cat,
searchable with grep, openable in any editor you already have. That is what
the format is for.
Does Tisty use AI? No, and none is coming. The natural language that turns "call the bank at 3" into a task is rules running on your machine: no model, no request, no cloud. If you already use an assistant of your own, Tisty leaves an MCP door — you open it, you can close it again, and until you do everything it tries is refused.
Can I use it on two computers? Yes, two ways. Connect your own Google Drive, OneDrive or WebDAV server in the window, and Tisty talks to it directly, keeping its copies in a place of its own there and seeing nothing else — encrypted with a phrase only you know, if you want. Or use a folder you already sync: Google Drive, OneDrive, iCloud, Dropbox, a NAS, a drive you plug in on Fridays. Either way there is no server of mine in between, no account of mine, and you can move from one to the other whenever you like.
Is there a mobile app? No. Tisty is a desktop program for Windows and macOS. Your documents are Markdown in a folder, so a phone that reaches that folder reads and edits them with whatever app you like — but the window, the spread and the archive are the desktop's.
Does it run on Linux? No. Tisty is a desktop program for Windows and macOS. An assistant that runs on Linux inside Windows, under WSL, reaches it all the same: Settings › Assistants connects it.
Is my data encrypted? On your disk, no, and that is a decision rather than an oversight: your operating system's permissions are the protection, and the files stay readable with tools you already have. In a cloud Tisty reaches directly, it can be: Settings › Security encrypts it with a 24-word phrase only you know. PRIVACY.md and SECURITY.md write it out, including the parts that are not reassuring.
Can I use it with my team? No. Tisty is for one person by design — no assignees, no permissions, no boards — and you deserve to know that before you install it rather than after.
Can I bring my notes over from another app?
Documents, yes: Import a document in the tree takes a .md, .markdown,
.txt, .html or Word .docx file and brings it in one at a time as
Markdown — Word to Markdown, HTML to Markdown, Obsidian to Markdown — and pasting
from Word, Google Docs or a web page converts the same way. A .tistyx from
another Tisty machine unpacks whole. Tasks have to be typed. There is no importer
for another program's task list, and one that guessed would cost you more than
the typing.
Are the downloads signed? Yes. The macOS disk images are signed and notarised by Apple, and the Windows installer is signed too — a copy from the Microsoft Store or from Homebrew carries that already. Tisty also refuses to install an update that is not signed with a key compiled into the copy you are running.
Does it work with a screen reader? Not as far as anybody knows, and that is worth saying plainly: the whole window works from the keyboard and that path is tested, but nothing has ever been tried with a real screen reader. If you use one, an issue saying where it falls apart would be the most useful thing anyone could send.
How is it different from Obsidian, Notion or Todoist? Tisty keeps tasks and documents in one store and one search, and finishing a task keeps everything it gathered instead of hiding it. The table below says where each of those is stronger.
Alternatives
Other places to keep notes and tasks, so you can pick the one that fits. Platform, storage and licence checked against each project in September 2026; everything else changes, so go and look.
Project | Platform | Where your data lives | Licence |
Tisty | Windows, macOS | Your disk, no account | AGPL-3.0 |
Windows, macOS, Linux, iOS, Android | Your disk; syncing is a paid extra | Closed source, free for personal use | |
Windows, macOS, Linux, iOS | Your disk | AGPL-3.0 | |
Windows, macOS, Linux, Android, iOS | Your disk; syncing through a service you pick | AGPL-3.0 | |
Windows, macOS, Linux, Android, iOS | Your disk, or a server you pick | AGPL-3.0 | |
Windows, macOS, Linux | Your disk, synced encrypted | Any Source Available 1.0 | |
Self-hosted, in a browser | A server you run | MIT | |
Windows, macOS, Linux, mobile | Your disk; syncing through a service you pick | MIT | |
Command line | Your disk | MIT | |
macOS, iOS | Your device; their cloud to sync | Paid, closed source | |
macOS, iOS, Windows, Android, web | Their cloud; a local folder gives up sharing | Freemium, closed source | |
Everywhere | Their servers, and an account | Freemium, closed source | |
Everywhere | Their servers, and an account | Freemium, closed source |
What Tisty does that most of these do not: tasks and documents in one store and one search, an archive that keeps a finished task whole instead of hiding it, the Eisenhower matrix by its name rather than a number from one to four, and a door for the assistant you already use with no AI inside the program itself.
Each of them is better than Tisty at something. Obsidian and Logseq are notebooks with a decade of plugins, and tasks are one of those plugins' job. Craft makes the handsomest document of the lot, and asks you to keep it in its cloud for the sharing to work. Notion models anything you can describe, once you and your data have an account there. Todoist and Things are quicker at catching a task than anything here — and when that task is done, what you worked out on the way has nowhere to stay. Joplin and AppFlowy are the closest in spirit to this one, and either is worth your time if a phone matters to you more than an archive.
Localization
The window, the guide, the welcome and the natural language all speak the language you chose the first time Tisty opened, and Settings changes it whenever you like.
Language | Tag | Status |
English | en | Complete |
Spanish | es | Complete |
Want yours in there? Open an issue
and say so — the window's strings live in one file, app/src/locales.ts, and
the rest follows from it.
Other Tools by the Same Author
Same idea, same terms: free, open source, no ads, no telemetry, everything local.
Support the Project
Tisty is free and will stay free: no ads, no premium tier, no paywall. If it saves you time and you would like it to keep being maintained:
And if you would rather not pay for anything, that is entirely fine. Star the repository so somebody else finds it, tell one person it exists, or open an issue when something is wrong. That is worth as much.
Standing On
Tisty is small because other people's work does the heavy lifting.
The core, in Rust — Tauri puts a native window around it without shipping a browser; serde reads and writes every line of the log; jiff does the dates and the time zones, which is the part nobody should write twice; SQLite, through rusqlite, holds the read cache; ULID gives every task an identifier that sorts by time and needs no coordination.
The window — React draws it and Tailwind CSS styles it; CodeMirror is where a document is written, a block at a time, while pulldown-cmark reads the Markdown in the core and ammonia keeps any HTML in it harmless; Mermaid draws the diagrams a code block describes, React Flow is the canvas they are drawn on by hand, and KaTeX sets its formulas; lowlight and highlight.js colour the code; webview2-com reaches the engine that lays the PDF out on Windows; Vite builds it and Vitest tests it.
The full list, with versions and licences, is in THIRD-PARTY-BUNDLED.md, and the licence texts the crates carry are in THIRD-PARTY-LICENSES.md; the About screen shows both.
Contributing
Read CONTRIBUTING.md. Open an issue before writing code for anything beyond a fix: Tisty is deliberately minimal, and a well-written feature can still be declined — usually because it would make the tool something other than what it is.
Everyone taking part — in issues, pull requests or discussions — follows the Code of Conduct.
Licence
AGPL-3.0. Using Tisty is covered by short terms of use that take nothing away from it.
Other terms
Commercial terms exist for organisations that cannot comply with the AGPL.
The signed builds in the app stores carry their own terms, because the stores' do not accept the AGPL — DISTRIBUTION.md says which applies to what you have, and why. Nothing is withheld from the source either way.
Project health
Available Tools
41 toolsappend_docAdd to a document, or to a task's pageADestructive
Add to a document that exists, at the end or under a heading you name. What is already written stays exactly as it is — you are adding, never rewriting, so nothing the person wrote can be lost and no print is needed. For what is chronological by nature — a log, minutes, the dated notes on a task's page. For a fact that changed, edit_doc the passage that says the old one: adding the new fact under the old leaves the document saying both. With under you can put a paragraph in the right part of a long document without reading any of it; outline_doc tells you which headings there are. The answer says how many characters it grew by; with echo it hands back the lines around what you added. A task's page takes it too, named by the task's id, on a task an agent filed or one the person opened to agents: what you add goes under the assistant's own notes, dated and signed, never among their words. On a task's page, replace writes the assistant's notes again whole instead of adding.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title — or a task's id, to add to that task's page | |
| body | Yes | Markdown to add. A blank line is put between this and what was there | |
| echo | No | Hand back the lines around the change as well, instead of reading the document again to see it | |
| under | No | A heading to add under, written as it reads. It goes at the end of what that heading holds, before the next one of its rank. Left out, it goes at the end of the document | |
| replace | No | Only with a task's id in `doc`: the assistant's notes on its page are written again, whole, as `body` — one dated digest of state, decisions, what was ruled out and references. The rest of the page stays as it is, a box in it never becomes a step, and what it replaced is kept for `restore_doc` with the task's id | |
| keep_compaction | No | Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: append semantics ('nothing the person wrote can be lost'), the return value (`grew` character count, `echo` surrounding lines), the task-page permission rule ('on a task an agent filed or one the person opened to agents'), and that `replace` writes the assistant's notes whole while `restore_doc` keeps the prior version. The one tension is the emphasis on never rewriting versus destructiveHint=true, but the destructive `replace` path is disclosed rather than hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence and every later sentence adds distinct information (edit-vs-append rule, heading workflow, task page behavior, return shape). It is dense and the long em-dash sentences take effort to parse, but little is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing what comes back (`grew` count, `echo` lines). It also covers the less obvious task-page mode and the `replace`/`restore_doc` interaction, so nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the structured fields already carry the definitions and the description mostly restates them (`under`, `echo`, `replace`, `keep_compaction`). Where it does add value is procedural: `under` lets you place text without reading the document and `outline_doc` finds the heading, and `replace`/`keep_compaction` are tied to their preconditions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb, resource and scope: 'Add to a document that exists, at the end or under a heading you name.' It also implicitly separates itself from editing/writing siblings by naming `edit_doc` for corrected facts and describing the task-page variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('For what is chronological by nature — a log, minutes, the dated notes on a task's page') and an explicit when-not plus alternative: for a changed fact, use `edit_doc` on the passage, because appending leaves the document saying both. It also routes to `outline_doc` to discover headings before using `under`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
archive_docPut a document or one of its pages away, or bring it backAIdempotent
Put a document away when the person asks for that, and bring it back with archived false. «Delete it» is flag_doc instead. Nothing is deleted and no text changes: docs and find reach the archive as well, unless their scope says otherwise. A single page can be put away on its own, and it stays where it lives — under its document, greyed and read-only — rather than moving to the archive. Putting the document away covers its pages too, and bringing it back wakes each page as it was: one that was already apart stays apart. Putting a document away is not the same as finishing a task — a task is the person's to close, and there is no tool here for that.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| folder | No | A folder to file it in as it goes, or as it comes back, by its name, its whole path or its id. It is filed either way: what the archive holds can still be put where it belongs | |
| archived | No | True to put it away, which is what happens if you leave this out; false to bring it back |
TDQS
A4.1/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: nothing is deleted, no text changes, `docs` and `find` still reach the archive, page-level archiving is greyed/read-only in place rather than moved, and restoring wakes pages exactly as they were with already-separated pages staying separate. That is precisely the kind of state semantics the readOnly/destructive/idempotent hints cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action and the delete-vs-archive distinction are front-loaded, and each subsequent sentence carries distinct state semantics. It is on the long side and the page/document paragraph could be tightened, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a mutation tool with no output schema and full schema coverage: mutation scope, reversibility, and page-level effects are all covered. The only gap is the unexplained relationship to the `restore_doc` sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description reinforces the `archived` default and the page-vs-document behaviour, but adds nothing about the `folder` parameter beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope ('put a document away... bring it back with `archived` false') and explicitly distinguishes it from `flag_doc` (delete). It does not differentiate from the sibling `restore_doc`, which appears to cover the same 'bring it back' action, leaving a real ambiguity for the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear triggers ('when the person asks for that'), names an alternative for the confusion case ('«Delete it» is `flag_doc` instead'), and rules out task-closing ('a task is the person's to close'). The overlap with `restore_doc` and `file_doc` is left unaddressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
attachKeep a file with a task or in a documentA
Copy a file from this machine into Tisty and keep it in one of two places: name a task and it goes on that task's journal, with where it came from written down beside it; name a doc and it is added at the end of that document, shown there as a picture or a card. An .html or .htm page attached to a document is drawn there as a live widget, sealed like a ```widget block and with the same classes and colours, which suits a page too large to write inline; to show it as a plain card instead, give its reference the title "file": . One or the other, never both. The file is copied, not linked. A task and a document both take files up to 650 MB — a recording, a video, a slide deck. Only attach what you were asked to.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | The document's id, if it goes in a document — an opaque name like `q7ntmzbm-0001`, which `docs` lists | |
| path | Yes | A path to a file on this machine | |
| task | No | The task id, if it is kept with a task | |
| label | No | What to call it. Defaults to the file's own name |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (not read-only, not destructive, not idempotent, closed-world), yet the description adds real substance: the file is copied rather than linked, both destinations accept up to 650 MB, and .html attached to a document renders as a live widget with the same classes as a ```widget block. It never states what happens on repeated attach (relevant given idempotentHint=false) or what comes back, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose and destination routing before the HTML widget caveat, and every sentence carries information. It is a single dense run-on paragraph though, and the inline `` example arrives with little framing, making it harder to parse than the rest.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation with annotations but no output schema, the description covers destination semantics, size limits, rendering behavior, and copy-vs-link. The notable gap is return behavior — with no output schema, the agent gets no hint about what reference or identifier comes back after attaching.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns extra by establishing the task/doc mutual exclusivity, which the schema does not express, and by describing the rendering consequence of each destination. The `label` parameter and the `"file"` title trick are described in overlapping, somewhat interchangeable language that could confuse which mechanism governs the display name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb ("Copy a file") and resource, then immediately scopes the two possible destinations (task journal vs. document end). An agent knows exactly what the tool produces and how each destination differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing conditions — name `task` vs. name `doc` — plus the hard exclusion "One or the other, never both" and a restraint instruction ("Only attach what you were asked to"). It never names a sibling alternative (e.g. page_doc or file_doc) for the case where a different tool is the right one, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
catch_upWhere things stand, and what has movedARead-onlyIdempotent
One call to start on: the lists, the folders, the tags already in use, how much there is, the documents written most recently, and a cursor. Send that cursor back as since next time and what moved comes with it — the tasks touched and the documents written, whoever did it — beside the lists, the folders and the tags, which come every time. It is meant to be the first thing you ask and the thing you ask again when you come back, in place of lists and tags and a blind docs.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | A `cursor` a previous `catch_up` handed back. It adds what moved since to the answer; where things stand comes either way |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds the non-obvious behavior: results are split into a stable core (lists/folders/tags every time) and a delta computed from the returned cursor. That cursor round-trip is the key operational trait and is explained clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with 'One call to start on' and covers the essentials in two sentences. The second sentence is long and comma-chained, but every clause (delta contents, who did it, the constant core) carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must convey the return shape — and it does: the standing lists/folders/tags, counts, recent docs, and a cursor, plus what the delta adds. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains `since` as a prior cursor. The description reinforces this by stating that passing it back yields what moved while the standing state comes either way, which adds clarity about the field's effect beyond the schema wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource bundle: returns lists, folders, tags in use, sizes/counts, recently written documents, plus a cursor. It also names the siblings it replaces (`lists`, `tags`, `docs`), so an agent can distinguish it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit: 'meant to be the first thing you ask and the thing you ask again when you come back, in place of `lists` and `tags` and a blind `docs`.' This tells the agent both when to use it (session start, return visit) and which alternatives it supersedes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describeDescribe a taskADestructiveIdempotent
Write the description of a task you filed, or one the person opened to agents: what it is, in the Tisty language. One already there is written over whole, so read it first and keep what still holds; what you learnt on the way goes in note.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What the task is, in the Tisty language | |
| task | Yes | The task id |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so this is a lower-bar case. The description still adds real context: the write replaces the whole existing description rather than merging, and the read-then-keep-what-still-holds guidance tells the agent how to avoid losing content. It does not say how errors or unknown task ids behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler: the operation and its scope first, then the overwrite caveat and the read-first remedy. Every clause carries an actionable instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the definition covers the destructive overwrite, the prerequisite read step, and where alternative information belongs. The remaining gaps are edge behavior, such as error handling and what the note is attached to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds modest semantic context, that `task` may be someone else's agent-facing task and that `body` is expressed in the Tisty language, but nothing about the id or content format beyond what the schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: write the description of a task, in the Tisty language. It also scopes which tasks qualify (ones you filed, or ones the person opened to agents), which distinguishes it from doc-editing siblings. It stops short of naming the sibling writers it supersedes (note, reword_note), so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit prerequisite and an alternative: 'One already there is written over whole, so `read` it first and keep what still holds', and it routes incidental findings to `note` instead of this tool. That covers when and where-else, though it does not state when not to use it at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
docsThe documents and the foldersARead-onlyIdempotent
Everything written down to consult — not the words a task keeps with it, which come with the task — the one written most recently first, with the folder each one sits in, whether it was put away, whether it is locked, and for each one what it is about: how many words it holds, how many sections, and the words it leans on. That is enough to pick which document to open without opening any of them; the print of the one you go on to edit comes back from read_doc or outline_doc. Ask for it before writing, so you do not write again what is already kept.
| Name | Required | Description | Default |
|---|---|---|---|
| deep | No | With `folder`: the documents of the folders below it too | |
| after | No | Skip this many. With `total` higher than what came back, ask again with `after` set to how many you have | |
| limit | No | At most 200, 50 by default | |
| scope | No | Defaults to either | |
| folder | No | Only the documents that sit in this one folder, by its name, its whole path or its id. Pages are left out — they are kept where their document is — and what the folders below it hold is theirs, not this one's: the answer names them under `below`, and `deep` brings their documents | |
| folders | No | Send every folder back too, with its id, path, icon and how much it holds. The answer already names them all in its text, so ask for this only when a name is not enough | |
| page_of | No | Only the pages of this one document, by its id, in reading order |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With read-only and non-destructive annotations already provided, the description adds useful behavioral context: results are ordered most recently first and include folder, archived/locked status, word and section counts, and keyword metadata. It does not discuss pagination or limits, but the schema covers those details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably short and front-loads what the tool returns, then moves to how it should be used. Its ornate phrasing ("the words it leans on", "the print") is less direct than ideal, but no sentence is clearly wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description explains the returned document metadata well enough to choose a document without opening it. It covers ordering, filtering context, and alternatives for reading content, leaving only minor details such as pagination to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the rich input schema already explains for `folder`, `deep`, `page_of`, `after`, and other options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as "Everything written down to consult" and clearly excludes task-kept words. It also distinguishes the tool from `read_doc` and `outline_doc`, which return document content, though it does not use a direct verb like list or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Ask for it before writing" gives explicit when-to-use guidance, and "the print ... comes back from `read_doc` or `outline_doc`" names alternatives for reading content. It does not explicitly compare against every sibling such as `find`, but the main usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_docChange a passage of a documentADestructiveIdempotent
Replace one passage of a document with another, named either by what it says with old or by where it sits with section or a line range — which let you change a part of a document you never read. What it said before is kept first, and if that cannot be done the edit is refused rather than made; restore_doc puts it back. The answer says how many characters the document grew by, which is worth reading: an edit should not change the size by much more than what you sent.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last line to replace. Left out, it runs to the end. It goes with `from`: on its own it names no place and the edit is refused | |
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| new | Yes | What takes its place. Empty takes the passage out | |
| old | No | The passage as it is written now, copied from `read_doc`, matching one place only — take in the lines around it if a short one would fit twice. Leave it out when naming a `section` or a line range | |
| echo | No | Hand back the lines around the change as well, instead of reading the document again to see it | |
| from | No | First line to replace, counting from 1. Needs `print` | |
| No | The print the document read at, from `read_doc` or `outline_doc`. It goes with `section` or a line range and nothing else uses it: an edit named by `old` is matched against the text itself. If anyone wrote since you took it, nothing is changed and you are told to ask `outline_doc` where the passage sits now | ||
| section | No | One heading and everything under it, named by its number and not by its words: the `at` of a heading in the `outline` `outline_doc` hands back, counting from 0. Needs `print` | |
| keep_compaction | No | Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: prior content is kept first, the edit is refused if that cannot be done, a stale `print` causes nothing to change and instructs the agent to re-outline. These are real safety and atomicity semantics the annotations don't carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause and every sentence carries content, but the run-on, stylized sentences (especially on `grew`) are denser than needed and slow scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return value (`grew` and why to check it), the conflict/refusal path, and the recovery route via `restore_doc`. An agent has everything required to call this destructive tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the prose adds cross-parameter logic the schema can't express: which parameters pair with which addressing mode, and that `print` is unused when matching by `old`. That is genuine added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Replace one passage of a document with another') and immediately explains the three addressing modes. An agent can distinguish it from write_doc, append_doc and restore_doc without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes between addressing alternatives ('named either by what it says with `old` or by where it sits with `section` or a line range') and points to `restore_doc` for undoing. It doesn't explicitly contrast against write_doc/append_doc, which is the only gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_tableChange a table in a documentADestructive
Read or change one table of a document by what its rows and columns are called, never by its Markdown: set a cell, add or remove a row, sort, rename a column, give it a type, add or remove a column. A row is named by the words of its first cell and a column by its title, as show hands them back. A value is written the way its column's type reads it — 1234.5 for a number, 2026-10-28 for a date, true for a checkbox — and one that does not fit is kept as sent and named in the answer. What the document said before is kept, as with edit_doc.
| Name | Required | Description | Default |
|---|---|---|---|
| do | No | What to do. Defaults to show, which changes nothing and hands back the columns with their types and the rows by their first cell | |
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| row | No | For set and remove: the row, by the words of its first cell or its number from 1 | |
| down | No | For sort: from the largest down. Defaults to from the smallest up | |
| type | No | For type and add_column: the column's type as written between braces in its head, such as `number`, `money USD sum`, `date`, `check` or `select`; `language` with the topic `tables` lists them. Empty takes the type away | |
| table | No | Which table, by its number from 1 or by the heading over it. Left out when the document holds only one | |
| title | No | For rename and add_column: the column's title | |
| value | No | For set: what goes in the cell. Empty clears it | |
| column | No | For set, sort, type, rename and remove_column: the column, by its title or its number from 1 | |
| values | No | For add: each column's title with what goes in it. Columns left out stay empty | |
| keep_compaction | No | Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and non-idempotent, and the description adds context they don't cover: prior document state is preserved as with `edit_doc`, and values that don't parse against the column type are kept as sent and reported back in the answer. It does not restate safety hints, which is correct.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and resource, then the operation list, then addressing, then value typing, then history behavior — each sentence adds a new fact. The prose is dense but idiomatic; no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, mutation-capable tool with no output schema, the description covers addressing, value coercion, failure handling, history preservation, and deferral to `language` for type names. Only the response shape is left implicit (partially indicated by the 'named in the answer' remark).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes beyond it by specifying how values must be formatted per column type (1234.5 for a number, 2026-10-28 for a date, true for a checkbox) and what happens when they don't fit — detail the schema does not carry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — read or change one table of a document — and enumerates the exact operations (set a cell, add/remove row, sort, rename column, set a type, add/remove column). That maps cleanly onto the enum values and separates it from doc-level siblings like edit_doc and write_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the addressing convention clearly (rows by the words of their first cell, columns by title, both interchangeable with numbers per the schema) and points to `show` as the way to obtain those names and to `language` with topic `tables` for the type vocabulary. It never explicitly says when to use edit_doc vs edit_table, so routing guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
export_docTake a document out to a folder on this machineAIdempotent
Write a document out as markdown files in a folder the person can reach, with its pages numbered in reading order and its attachments beside them. Nothing here changes and nothing is deleted: an export is a copy. Use it to hand work to something outside Tisty.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| into | Yes | A folder that exists on this machine, which an export of this document has not been taken to already: one is made inside it, named after the title, under Downloads, Documents, Pictures, Desktop or the temporary folder |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false and idempotentHint=true, and the description reinforces this with 'Nothing here changes and nothing is deleted: an export is a copy.' It goes further by disclosing the output layout — pages numbered in reading order, attachments placed beside them — which annotations cannot express. It does not note that files land on the local filesystem side (the reason readOnlyHint is false), leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the tool produces, followed by the non-destructive guarantee and the routing hint. No redundant restatement of the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully explains what the export produces (markdown files, ordered pages, adjacent attachments), which is exactly what an agent cannot learn from structured fields. Only minor gaps remain, such as what happens when the target subfolder already exists, though `into` hints at that constraint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both `doc` (opaque id from docs, not title) and `into` (existing folder, not previously exported to, subfolder named after title) fully documented. The description adds only the loose notion of 'a folder the person can reach', so the schema does the heavy lifting and baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (write out as markdown files), resource (a document, its pages and attachments), and destination (a folder on this machine), which immediately separates it from sibling writers like write_doc, edit_doc and import_doc. The 'export is a copy' framing makes the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use it to hand work to something outside Tisty' gives a concrete selection rule against the in-place editing siblings. It stops short of naming an explicit alternative or a when-not condition (e.g. use import_doc to bring content back in), so it is clear context without full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
file_docPut a document, or several, in a folderAIdempotent
Move a document into a folder, or out of every folder by leaving folder out. Nothing is deleted and no text changes. Moving is not writing, so a document the archive holds by itself moves too and stays put away: that is how something already archived is filed where it belongs.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The id of the document to file, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title. A list of ids does the same to all of them in one go, and if one of them cannot, none of them moves. | |
| folder | No | An existing folder, by its name, its whole path or its id. Leave it out to take the document out of every folder |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive=false and idempotent=true, but the description adds real context beyond them: nothing is deleted, no text changes, and an already-archived document still moves while remaining archived. That last point is a non-obvious behavioral interaction (filing vs. archive state) that no annotation conveys. It does not cover error/atomicity behavior, though the schema does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and the optional-parameter rule. The final sentence's phrasing ("moves too and stays put away: that is how something already archived is filed where it belongs") is a bit circuitous but still carries distinct information, so nothing is truly wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, non-destructive filing tool with no output schema, the description covers the mutation model, the archive interaction, and the omission case; the schema covers ids, batch atomicity, and folder acceptance. The only gap is that batching ("or several") appears in the title but never in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's only parameter-level statement — leaving `folder` out removes the document from every folder — restates what the schema already says verbatim in the `folder` property, so it adds no new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Move a document into a folder") and adds scope (nothing is deleted, no text changes), so an agent immediately knows this is a filing operation rather than a content edit. It stops short of naming the sibling `move` tool or clarifying the document-vs-other-resource boundary, and only the title (not the description) mentions filing several documents at once.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is one concrete usage rule — omit `folder` to take the document out of every folder — which is genuinely contextual. However, there is no explicit when-to-use versus alternatives (write_doc, edit_doc, move, archive_doc), leaving the agent to infer the boundary from the description's tone rather than from a stated condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
findSearch the list and the archiveARead-onlyIdempotent
Search the tasks — open and archived alike — and the documents: by words with query, by what a task is with the sifting fields (alone or narrowing a query), or by source alone to see whether something was filed from it already. A task found by what its page, description, steps or notes say comes with in and the line that says it, so a past decision often reads without read. With doc it searches inside that one document instead and hands back the matching lines with their numbers and the section each sits in.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Its date or deadline on this day or before | |
| doc | No | Look inside this one document rather than across the tasks. Hands back the lines where every word of the query turns up, accents or not, with their numbers, the lines around them unless every one of those is blank, and the section each sits in. A line in `around` is cut at 200 characters; `read_doc` with `from` and `to` brings it whole | |
| tag | No | Carrying this tag, with or without the #. Any sifting field leaves the documents out of the answer | |
| from | No | Its date or deadline on this day or after (2026-08-31) | |
| list | No | In this list, named as `lists` names it | |
| after | No | Skip this many tasks, to page on while `total` is higher than what came back. Documents are not paged: `docsTotal` says how many match, and a higher `limit` brings more | |
| limit | No | At most 100, 20 by default | |
| query | No | Words to look for, not a phrase: each word has to turn up in the same task or document (on the same line, with `doc`), in any order, accents or not; put a phrase in quotes when the order is the point. Not needed when sifting by the fields below | |
| scope | No | Defaults to either: the open tasks and the archive together, which is where how something was solved before is found | |
| around | No | With `doc`: how many lines to bring on each side of a hit, 1 by default, 0 for none, at most 10 | |
| folder | No | Only the documents in this folder and the folders below it, by its name, its whole path or its id. Documents whose title says the words come first either way, before those that only mention them | |
| source | No | Ask whether this exact source was proposed already | |
| part_of | No | Only the parts of this task, by its id | |
| by_agent | No | True for what an agent filed, false for what the person wrote | |
| said_done | No | True for what an agent spoke for — said done, or said should not be done — and the person has not decided yet; false for what nobody spoke for | |
| from_source | No | Only tasks whose `source` starts with this, however it is written: «sereno», «sereno#» and «sereno: » all bring everything read out of that one place | |
| open_to_agents | No | True for the person's own tasks they opened to agents — yours to fill in and to say done — false for what they kept to themselves |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only, idempotent, non-destructive profile, and the description goes further by disclosing result shape: hits come back with `in` and `line`, doc mode returns numbered matching lines with surrounding context and section, lines are truncated at 200 characters (use `read_doc` for whole text). Paging behavior for tasks (`total`, `after`) versus documents (`docsTotal`, `limit`) is also surfaced. Not exhaustive on ranking or ordering outside the folder case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and target, but written as a single dense paragraph of long, clause-heavy sentences ('by words with `query`, by what a task is with the sifting fields...'). Most content earns its place, yet the turgid phrasing makes the mode selection harder to scan than a short bulleted breakdown would.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 optional parameters and no output schema, the description carries the burden of conveying return shape, and it does so reasonably: `in`/`line` tagging, doc-mode line numbering with context and section, truncation limits, and both paging mechanisms. A brief note on default result ordering would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter in detail. The description adds a little relational meaning — that sifting fields can stand alone or narrow a `query`, and that `doc` switches the whole search target — but most of its parameter talk (query word matching, `source`, `doc`) duplicates what the schema descriptions already say. Baseline 3 fits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb+resource and scope: 'Search the tasks — open and archived alike — and the documents', and names the three query modes (query words, sifting fields, source). It is distinguishable from siblings such as read_doc and read, which it explicitly references, but the first sentence is long and compounds several modes before the scope is fully settled.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains how to pick a mode: words via `query`, task attributes via the sifting fields ('alone or narrowing a query'), or `source` alone to check prior filing. It also signals a sibling substitution ('a past decision often reads without `read`'). No explicit when-not-to-use or a full alternative routing to `docs`/`read_doc`, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
flag_docSay a document has had its day, which is how a document gets deletedAIdempotent
The tool for «delete this document», and the only one: you cannot delete, so you mark and the person deletes. Mark a document you found is no longer worth keeping — a copy of another, notes folded into a living document, a handover for a flow that was retired — with its reason, where what it said lives now in instead, and in body what makes it old and how you know. Several copies of one thing go in one call, marked alike, so the person settles the set with one click. The mark changes nothing: the document reads the same, stays where it is, and the person sees the mark when they open it. Deleting it and taking the mark off are theirs, from the window; archive_doc puts it away only when they ask for that. One mark at a time — a document already marked is refused until the person has looked, and in a set it is skipped and named.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The id of the document to mark, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title. A list of ids marks them all alike in one go | |
| body | Yes | What makes it old and how you know, in the person's language: what it describes that no longer exists, and what replaced it | |
| reason | No | Why it has had its day: a duplicate of another, moved into another (only once what it holds worth keeping is there), superseded by another, wrong, obsolete, or a scratch nobody needs | |
| instead | No | The id of the document or the task that holds what it said now. Needed with duplicate_of, moved and superseded |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description goes well beyond: 'The mark changes nothing: the document reads the same, stays where it is, and the person sees the mark when they open it' — so the agent knows the write is a non-destructive annotation, not content mutation. It also discloses the refusal/skip behavior on already-marked docs, which is the practical consequence of idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It front-loads the capability and the constraint, and each paragraph has a job: what it is, what to write, how batching works, what the mark does not do, and the refusal edge case. The prose is somewhat ornate ('has had its day', 'with its `reason`, where what it said lives now in `instead`'), which costs a bit of scannability but not correctness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool with annotations, no output schema, and full schema coverage, the description covers everything an agent needs: the division of labor with the human, the visibility of the mark, the batching behavior, and the failure mode on already-marked documents. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the field docs: the batch-marking intent for the doc array ('several copies of one thing go in one call, marked alike') and the conditional requirement that `instead` pairs with duplicate_of/moved/superseded. It stops short of adding format or syntax detail beyond the schema, hence not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus its real-world framing: 'The tool for «delete this document», and the only one: you cannot delete, so you mark and the person deletes.' That immediately distinguishes it from mutation siblings like archive_doc, restore_doc and edit_doc — the agent knows this is the soft-delete-request path, not a hard delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use with concrete examples (duplicate, notes folded into a living document, handover for a retired flow) and an explicit when-not-to-use alternative: 'archive_doc puts it away only when they ask for that.' It also gives the batching rule ('several copies of one thing go in one call') and the refusal condition for already-marked docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
folderMake a folderAIdempotent
Make a folder for documents, and give it an icon and a colour if they fit. If a folder by that name is already there it is used as it is — and without inside, one by that name is found however deep it sits, so a name you mean as a new top-level folder may hand you one inside another. An icon or colour you send changes how it looks; nothing is renamed, moved or deleted. Folders hold documents, not tasks; tasks go in lists.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | A single emoji, or one name from the drawn catalogue: home, work, money, study, travel, health, food, family, code and the like. An emoji is often the plainer choice | |
| name | Yes | A word or two, at most 40 characters. It is the folder's own name, never a path: send the whole path only to say where to nest it, and then every step but the last has to exist already | |
| color | No | red, orange, amber, green, teal, blue, indigo, purple, pink, brown or gray | |
| inside | No | An existing folder to nest it in, by its name, its whole path or its id. Four deep at most |
TDQS
A4.2/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that a name collision returns the existing folder unchanged, that the lookup is recursive when `inside` is absent, that icon/colour only affect appearance, and that "nothing is renamed, moved or deleted." These match idempotentHint=true and destructiveHint=false rather than contradicting them, and add the search-scope behaviour the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, purpose first, caveats after, no filler. The middle sentence is grammatically knotty ("If a folder by that name is already there it is used as it is") and forces a re-read, which costs some clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-destructive, idempotent create with a fully documented schema and no output schema, the description covers the collision behaviour, side effects, and nesting limit — the things an agent would otherwise get wrong. It does not say what the call returns (the folder, presumably) or whether icon/colour are applied when an existing folder is reused, a small ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining the semantic trap in `inside` — that without it the name match happens at any depth, so a requested top-level folder may resolve to a nested one. It adds little on `icon`/`color` beyond the schema, but the `inside` caveat is genuinely new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Make a folder for documents" gives a concrete verb and resource, and the closing line ("Folders hold documents, not tasks; tasks go in lists") separates it from the lists sibling. It stops short of a crisp one-line identity statement — the purpose has to be assembled from the first and last sentences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the create case, the reuse case (an existing same-named folder "is used as it is"), and gives a concrete warning about omitting `inside` picking up a nested folder of the same name. It never names an alternative tool for reading or moving folders, so routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
helpHow Tisty itself worksARead-onlyIdempotent
The pages of Tisty's own Help, the ones tisty.app shows: installing, tasks and how they are written, documents, pages and PDF, sync, encrypting the cloud and letting a computer in, assistants, keyboard shortcuts, privacy. Ask it when the person asks how Tisty does something, instead of guessing. Left alone it gives the index; a topic gives one page. lang picks English or Spanish.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en for English, es for Spanish. Left out, English | |
| topic | No | One page, named as the index names it. Left out, the index |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, read-only, idempotent, closed-world call, so the safety profile is covered. The description adds genuinely new behavioral facts: with no `topic` it returns the index, with a `topic` it returns a single page, and `topic` names must match the index's own naming. Return format detail is only sketched, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the resource, then the usage rule, then the default behavior — good ordering. The long inline topic enumeration duplicates the enum in the schema and makes the opening sentence a run-on, though it does aid routing at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Two optional, fully documented parameters, no output schema needed, and the description states exactly what comes back in both the default and topic-specified cases. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters carry enum descriptions, so the schema does the heavy lifting. The description restates the defaults (topic→index, lang→English) and adds only the mild clarification that topic values are 'named as the index names it', which is a marginal but real addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (Tisty's own Help pages, as shown on tisty.app) and enumerates the covered subject areas, which makes it unmistakable against document-oriented siblings such as read_doc, docs, and page_doc. An agent can tell this is product documentation, not the user's own content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it when the person asks how Tisty does something, and names the anti-pattern to avoid ('instead of guessing'). It does not name a sibling alternative or a when-not condition, so it falls short of a full routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_docBring a markdown file on this machine in as a documentA
Read one markdown file from disk and keep it here as a document, turning on the way in what the Tisty language has no word for into what it can say, and saying what it changed. Every file the text points at beside it — pictures, video, PDFs — is copied in too, and the text is pointed at Tisty's own copies: nothing is left pointing outside. What cannot come in has its link taken out rather than left dangling. The files on disk are left untouched. Nothing is turned away for what it holds: a document carrying what looks like a live credential comes in as written, with a warning at the top for the person to decide about. A task's page brought back hands the task its properties and its words, and makes no document. Takes folder and page_of like write_doc. One file per call — walk an export folder yourself and call it for each, so the person sees what happened to each one.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | A markdown file under Downloads, Documents, Pictures, Desktop or the temporary folder | |
| title | No | A title to put at the top, for a file whose first line is not one. Left out, the file name is used | |
| anyway | No | Bring it in although a document on the same subject is here already — only when this really is another subject; otherwise update that one | |
| folder | No | The existing folder its subject belongs in, by its name, its whole path or its id. Expected: left out, it sits outside them all, and that needs a reason | |
| page_of | No | The id of the document this becomes a page of |
TDQS
A4.2/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (not read-only, not destructive, not idempotent); the description goes well beyond them by disclosing that sibling assets are copied in, external links are rewritten or stripped, and the source files on disk are left untouched. It also flags the surprising non-blocking behavior on credentials ('comes in as written, with a warning at the top') and that the task-page case produces no document at all.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded, but the prose is heavily circumlocuted — 'turning on the way in what the Tisty language has no word for into what it can say' forces the agent to decode meaning that a plain word like 'converting' would deliver instantly. Length is defensible for the complexity, but sentence structure is needlessly opaque.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter mutating tool with no output schema, the description covers side effects, asset handling, the no-damage guarantee to source files, and even the return behavior ('saying what it changed'). The main remaining gap is that non-idempotency and the `anyway`/duplicate-document interaction are only implied rather than stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description only adds a cross-reference that `folder` and `page_of` behave 'like `write_doc`'; it says nothing beyond the schema about `anyway` or `path`, so it neither compensates nor detracts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause names a specific verb and resource — 'Read one markdown file from disk and keep it here as a document' — which cleanly separates it from write_doc (authoring) and read_doc (inspection). It also carves out the edge case where the file is a task page and 'makes no document', so an agent won't mispredict the outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'One file per call — walk an export folder yourself and call it for each' gives explicit usage guidance and steers the agent away from batching. 'Takes `folder` and `page_of` like `write_doc`' anchors it to a sibling's convention. It never states when to use this instead of write_doc or edit_doc for an existing document, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
languageWhat Tisty adds to MarkdownBRead-onlyIdempotent
Plain Markdown needs nothing from here: Tisty takes it as it is and turns it on the way in. Left alone this gives the index of what Tisty adds — pens and their colours, underline, icons, callouts, collapsible sections, tags, cards to other documents, attachments, references, diagrams — apart from what reads as Markdown anywhere. Ask with a topic for the one you mean to write, so a pen colour or an icon is one Tisty knows; «all» gives the whole guide. lang picks English or Spanish; the language itself is the same.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | en for English, es for Spanish. Left out, English | |
| topic | No | One part of the guide, named as the index names it, or all for the whole of it. Left out, the index |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds the useful note that lang switches content language but 'the language itself is the same', which goes beyond the schema. It says nothing about output size, format, or whether the guide is returned as text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the key exclusion (plain Markdown needs nothing), which is good, but the prose is ornately phrased and the long dash-list of topics is only partly useful since the schema already enumerates them. Several clauses could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-optional-enum, no-output-schema lookup tool, the description covers the main modes (index vs. topic vs. all, en vs. es). However, an agent still cannot tell what the returned payload looks like or how large 'all' is, which matters for a documentation-fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both params are enums with descriptions, so the baseline is 3. The description adds a bit of intent ('so a pen colour or an icon is one Tisty knows'), hinting that topics must match the documented names, but offers no syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that this returns a guide/index of what Tisty adds on top of plain Markdown, listing the covered areas. But it never states plainly that the tool returns reference documentation, and the framing ('turns it on the way in', 'what reads as Markdown anywhere') is oblique. It also does no work to distinguish itself from sibling `help`/`describe`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Plain Markdown needs nothing from here' is an explicit exclusion, and 'Ask with a `topic` for the one you mean to write' plus '«all» gives the whole guide' tells the agent when to use which mode. Only gap is that no alternative sibling (e.g. `help`) is named for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listsThe lists that existARead-onlyIdempotent
The names of the person's lists, so you can file a task into one. You cannot make a list; anything you propose without one lands in the inbox.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it cannot create lists, and any proposed task without a list goes to the inbox, which matters for downstream filing decisions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose and followed by an operational constraint. Every sentence adds useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless read tool with rich annotations and no output schema, the description is complete enough: it explains what is returned (list names), why to call it (filing tasks), and the fallback when no list is used (inbox). Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; this matches the baseline for parameterless tools. The description does not need to compensate for any schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (the person's lists) and what it returns (the names), plus its practical purpose: filing a task into one. It does not explicitly contrast with sibling tools such as tags or folder, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case ('so you can file a task into one') and a key limitation ('You cannot make a list'), which tells the agent when this tool is appropriate and what it cannot do. It does not explicitly name alternative tools or state when not to call it beyond the list-creation restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
moveHang a task under another, let it go, or put it in a listAIdempotent
On a task you may work on — one an agent filed, or one the person opened to agents. part_of hangs it under another such task as one of its parts, or with null lets it go to stand on its own. list puts a task an agent filed in a better list; a task the person filed keeps its list. One level only: a task with parts is no part, and a part holds none. A closed task, on either side, takes nothing, and a whole said done or not to be done takes no new part until the person decides.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | An existing list, by name, for a task an agent filed; `lists` says which | |
| task | Yes | The task id | |
| part_of | No | The id of the task to hang it under, or null to let it go from the one it is a part of |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key behavioral constraints: hierarchy is one level only, a task with parts cannot become a part, closed tasks on either side take nothing, and a done/not-done whole cannot receive a new part. These are meaningful operational details not captured by the annotations, and nothing contradicts the declared mutation/idempotency hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact paragraph with the core operation and constraints front-loaded. Some phrasing is cryptic and dense, such as 'a whole said done or not to be done,' but each sentence carries substantive information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relational mutation tool with no output schema, it covers the important preconditions and side effects: permission scope, one-level hierarchy, closed-task rejection, and done-task restrictions. It does not explain return behavior or error signaling, but the essential calling context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines all three parameters. The description still adds semantics beyond the schema: it explains what `part_of` null means, that `list` is only for agent-filed tasks, and how existing lists are preserved for person-filed tasks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explains two concrete operations: `part_of` hangs a task under another or releases it with null, and `list` moves an agent-filed task to another list. The purpose is clear despite the generic tool name, but it does not explicitly distinguish itself from siblings like `plan`, `unplan`, or `tick`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear applicability rules: the task must be one the agent filed or the person opened to agents, `list` only applies to agent-filed tasks, and closed or decided tasks take no new part. It stops short of naming alternative tools or explaining when to choose them over this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noteAdd to a task's journalA
Append to what a task has recorded. Only a task's: a note set apart inside a document is a callout, > [!NOTE], written with edit_doc. Works on tasks the person wrote too. Use it when something new turns up about work that already exists, instead of filing a duplicate. A closed task is history and takes no note: if the work came back, propose it anew.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What to record, in the Tisty language | |
| task | Yes | The task id |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a non-readOnly, non-idempotent, non-destructive write; the description adds real behavior beyond that — it is an append (so additive rather than replacing), it works on user-authored tasks, and it will not accept notes against closed tasks. The closed-task rejection is a concrete, callable constraint the annotations do not carry. It stops short of saying what a duplicate append does or what is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core operation and the when-to-use trigger are front-loaded, and every sentence carries a distinct rule (disambiguation from callouts, duplicate avoidance, closed-task behavior). The callout aside adds a clause of length but earns it by preventing a wrong tool choice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter append tool with full schema coverage and no output schema, the description covers purpose, trigger, sibling disambiguation, and the one notable failure mode (closed tasks). Given the non-idempotent flag, a brief word on repeated appends would make it complete, but nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with only two parameters, both already documented (task id, body in the Tisty language). The description adds no new semantics about `task` or `body` beyond what the schema states. Baseline 3 is appropriate when the schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Append to what a task has recorded" gives a specific verb (append) and resource (a task's journal), and the title fixes the term "journal" / "note". It also cleanly separates the concept from a document callout written with edit_doc, so an agent can tell it apart from write_doc/append_doc. The only softness is "what a task has recorded", which is evocative rather than precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use: "Use it when something new turns up about work that already exists, instead of filing a duplicate" — this names the alternative behavior (propose) it should replace. It also states an exclusion and its remedy: a closed task takes no note, so propose the work anew. Both the positive trigger and the refusal path are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
outline_docWhat is in a documentARead-onlyIdempotent
The headings of a document with the lines each one spans and how many characters it holds, how long the whole is, its print, and for a document with pages a row per page with its title, length and sections, in reading order — a few hundred tokens instead of the bodies. Ask for this first when a document is long or when you only mean to change one part of it: with the outline you know which section to read and what it costs, and with the print you can write into it without having read it at all. It also says which other documents point at this one, which is what you want to know before putting it away: those links go on pointing at it in the archive. by says whether an agent or the person began it and each page, alike names documents elsewhere whose title names the same subject as this one or one of its pages, and repeated the headings written in more than one page — the signs that it wants compacting. dead lists the links that lead nowhere, mislabeled the page lines showing another name than the page's title, and a page marked loose has no line naming it, so the window gives it no place.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent and non-destructive behavior. The description adds valuable detail: it enumerates additional metadata fields (by, alike, repeated, dead, mislabeled, loose), explains the token cost, and notes it omits document bodies, going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single dense paragraph with multiple clauses and semicolons, which makes it hard to parse despite containing useful content. The front-loaded opening is good, but the overall length and structure could be tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and annotations covering safety, the description is extremely complete: it covers return values, usage, costs, and metadata semantics. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter `doc` has full schema coverage including an example and format. The description does not add any further guidance about the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns document headings, section spans, character counts, print, and per-page metadata, which is a specific resource and output shape. It implies distinction from reading full bodies with 'a few hundred tokens instead of the bodies', but does not name a sibling tool explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Ask for this first when a document is long or when you only mean to change one part of it', giving clear when-to-use guidance. It also adds a second use case for backlink inspection before archiving, though it does not name a direct alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
page_docMake one document, or several, into pages, put their pages in order, or take them back outAIdempotent
Needs doc, or order with page_of. A page is real content related to one subject but not part of it — a runbook, a contract, an annex — never a session: a review, a day's progress or a PR's notes belong on the task. Hang a document from another as one of its pages, or take a page out by leaving page_of out, which makes it a document of its own again, back in the folder it came from. A page goes with its document everywhere — folder, archive and deletion — and holds no pages of its own. Hanging one writes the line that names it at the end of that document, the same line write_doc with page_of writes; after, before and at say where that line goes instead. Taking a page out writes nothing: the line stays where it was, now pointing at a document of its own, and taking it out of the text is yours to do. order is the third thing this does: it takes the pages of one document and deals the lines they already have back out in the order you name, which is how several are put in order in one call. The order pages are read in is the order their lines sit in the document, and nothing else. The line is , opening bang and all — without it the line is a mention in a sentence and gives the page no place — and a square bracket in the title goes in with a backslash before it.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Where to write the line when you are not naming a page to sit beside: "first" puts it before every page the document names, "last" after them all. It is what to send for a document whose pages no line names yet, since there is no page there to name | |
| doc | No | The id of the document to hang or to take out, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title. A list of ids does the same to all of them in one go, and if one of them cannot, none of them moves. | |
| after | No | The id of another page of that same document. The line naming this page is written straight after the line naming that one, which is what puts it next in reading order. Needs `page_of`, takes one `doc`, and the page you name has to have a line already | |
| order | No | The pages of one document, by their ids, in the order they are to be read. Their lines are moved into each other's places and nothing else in the text moves, so pages you leave out stay where they are. Two or more ids, each named once. Needs `page_of`, and goes on its own: no `doc`, `after`, `before` or `at` — one call says an order, another puts one page somewhere. Every page it names has to have a line of its own already | |
| before | No | The same, on the other side: the line goes straight before the one naming this page | |
| page_of | No | The id of the document it becomes a page of — an opaque name like `q7ntmzbm-0001`, not its title. Leave it out to make it a document of its own |
TDQS
A4.1/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses substantial behavior beyond the annotations: hanging a page writes a specific markdown line, removal writes nothing and leaves that line pointing at the now-independent document, and ordering only moves existing lines. It also explains cascading behavior with folder, archive, and deletion, plus the rule that pages cannot hold pages. This is unusually rich behavioral context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose is dense and frequently convoluted, with very long sentences and a requirements fragment before the purpose is stated. Most content is useful, but the structure would benefit from headings or bullets separating hang/remove/order modes. It is not concise enough for its complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex three-mode tool and no output schema, the description covers the important semantics: page definition, text-line effects, removal behavior, ordering behavior, cascading, and line format. It does not describe return values or failure responses beyond schema-level atomicity notes, but the behavioral coverage is otherwise strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter thoroughly. The description still adds meaning by explaining mode exclusivity ('order' with `page_of` and no `doc`/`after`/`before`/`at`, or `doc` for hanging/removing) and by giving the exact line syntax with escaping details. This is more than schema repetition, though much parameter detail remains in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies three specific operations: hanging a document as a page, taking a page out, and reordering pages. It also distinguishes pages from sessions/tasks and references the related `write_doc` behavior. It is clear once parsed, but the opening 'Needs `doc`, or `order` with `page_of`' delays the actual purpose, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage criteria, notably that a page is real related content such as a runbook or contract, never a session, and that review/progress/PR notes belong on the task. It also states mode constraints: `order` needs `page_of` and goes on its own, while omitting `page_of` removes a page. It does not explicitly compare this tool against all relevant siblings such as `attach` or when to prefer `write_doc` instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
planAdd steps to a taskA
Add a checklist, or more of one, to a task you filed or one the person opened to agents. Steps go after the ones already there; read shows them.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The task id | |
| steps | Yes | The steps to add, in order, one string each, at most 100 characters |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-readonly, non-destructive, non-idempotent mutation. The description adds useful behavioral detail that steps are appended after existing ones and that `read` can verify them. It stops short of explaining edge cases like duplicate additions or permission requirements, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the action front-loaded and zero wasted words. The append behavior and read reference are packed into the second sentence without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool with annotations and full schema coverage, the description covers purpose, scope, append behavior, and a verification path. It does not explain failure modes or limits beyond the schema, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that new steps go after existing ones, which is an ordering behavior not explicitly stated in the schema's 'steps to add, in order' phrasing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('a checklist, or more of one, to a task'), making the core action clear. It distinguishes the operation from viewing via `read`, but does not explicitly name or contrast with siblings like `unplan` or `reword_step`, so sibling differentiation is only partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a scope condition ('a task you filed or one the person opened to agents') and points to `read` for viewing, which implies when to use it. However, it does not explicitly state when not to use it or name alternatives for modifying existing steps, leaving usage guidance somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
proposePropose a taskA
Propose a task — something to do; what will be read again is a document (write_doc). Give it a title. Several read from one thread go together in tasks, each judged on its own, so a bad one does not sink the rest. A step is one line of a checklist; work that is several tasks with one end — a move, a release, a plan — goes in parts, one level deep, rather than packed into steps. A ticket's progress, its reviews, pull requests and audits are this task's page and its parts, never documents. Tisty tags it #agent by itself.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The day it is meant to be done, or with a deadline the day the work starts (2026-08-31) | |
| list | No | The existing list it belongs in, by name; `lists` says which. Expected: left out, it lands in the inbox, and that needs a reason | |
| tags | No | The subjects it is about, one word each in the person's plain words; capitals and accents decide nothing. Six is already a lot, and a word that merely appears in the title is no subject. Reuse what `tags` lists when it means the same | |
| again | No | Only when the person asks you in this conversation to do again what was already proposed from this source and closed since: files a new task despite the source being known. Say in the description how the last one ended. Never for a source whose task is still open | |
| parts | No | The tasks the work is made of, each shaped like a single one with its own steps; the task around them is finished when they are. One level, at most 32 here — add more later with `part_of` | |
| steps | No | A checklist, each step at most 100 characters; what needs more is a part | |
| tasks | No | Several at once, each shaped like a single one. Left out when proposing one | |
| title | No | What has to be done, in a line | |
| remind | No | When to ring, each like 2026-08-30T20:00. Only for what happens once at a set time and cannot be caught up on — an appointment, a flight — set the evening before; never for work any day will do, nor for what repeats | |
| source | No | Where you read it — a message id, a thread link | |
| part_of | No | The id of a task you may work on — one an agent filed, or one the person opened to agents — that this one is a part of | |
| deadline | No | The day it actually runs out (2026-08-31): only once it passes is the task overdue | |
| priority | No | Only if someone said so. Leave it out otherwise | |
| description | No | What you read, in the Tisty language |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a non-read-only, non-destructive, non-idempotent write. Beyond that, the description adds useful behavior: Tisty automatically tags the task #agent, and multiple tasks in one proposal are judged independently, so one bad task does not sink the rest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loads the purpose and key alternative to `write_doc`. Every sentence carries relevant semantics for a complex 14-parameter task-creation tool, though the phrasing is somewhat compressed and idiosyncratic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex creation tool with 14 parameters and no output schema, the description covers the major conceptual decisions: task versus document, grouping multiple tasks, steps versus parts, and automatic agent tagging. The main omission is that it does not describe what a successful proposal returns, such as a task id, which could matter for later `part_of` references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 14 parameters in detail. The description still adds conceptual clarity beyond the schema by explaining the relationship between steps, parts, and tasks, including that several tasks with one end belong in `parts` rather than being packed into steps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: propose a task. It explicitly distinguishes this from `write_doc` by saying that what will be read again is a document, so an agent can separate task creation from document creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage contrast: tasks are for something to do, while documents are for what will be read again, naming `write_doc`. It also explains that ticket progress, reviews, pull requests, and audits belong to the task's page and parts rather than documents, though it does not enumerate every possible alternative such as note or plan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
readRead a whole taskARead-onlyIdempotent
Everything one task holds: its description, its steps, its journal — each note with the id reword_note takes — its parts, what it keeps, and its document: the page the person reads and writes, with its sections and their grey hints, its boxes ticked as the steps are and its properties written at the top. Ask for it before adding a note, so you do not write down something already written, and before mending anything, so you change what is there now. With fields it brings only the parts you name, which is how to check one thing about a task whose journal is long. A closed task comes with closed and a notice, and reads as it ended: it is history to consult, and nothing on it changes. find with part_of brings the parts of any task, closed or open.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The task id | |
| fields | No | Only these parts of it: any of title, status, closed, notice, date, deadline, standing, reminders, tags, source, list, priority, by_agent, via, said_done, said_not_doing, open_to_agents, part_of, parts, description, steps, journal, kept, document. Left out, everything comes. The id always does |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive operation, so the description does not need to restate safety. It usefully adds behavior beyond annotations: closed tasks include `closed` and a `notice`, are historical, and do not change; `fields` limits the returned parts. It does not cover error behavior or missing-task handling, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core idea and includes useful context, but the first sentence is dense and heavily metaphorical, especially the document explanation with 'grey hints' and 'boxes ticked.' It is not padded with irrelevant material, but the structure could be clearer and more concise for a two-parameter read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining return contents, and it does so thoroughly: it enumerates task components and explains the document structure, closed-task response, and subset behavior via `fields`. It also explains the main alternative for parts retrieval, making the definition complete enough for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful use-case semantics for `fields`, explaining that it returns only the named parts and is useful for checking one thing about a task with a long journal. It adds less for the required `task` parameter, which the schema already describes sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The definition clearly identifies the resource and scope: it returns everything one task holds, including description, steps, journal, parts, kept items, and document. It is specific enough to distinguish from actions like note or tick, and it names `find` with `part_of` as a related alternative. It stops short of an explicit sibling contrast with `read_doc`, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to call it: before adding a note to avoid duplicate writing, and before mending anything to see current state. It also explains the `fields` variant for checking one thing on a task with a long journal, and points to `find` with `part_of` for retrieving parts across closed or open tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_docRead a document, or a part of oneARead-onlyIdempotent
The text of a document and the print it reads at. Left alone it brings the whole body; one past about 12,000 characters comes back as its outline instead, with whole set to false, and then you ask for a section, a run of lines or a budget of chars, about 12,000 at a time. Reading a part is the ordinary way to work: the print comes with every answer, so a passage can be changed with edit_doc without ever bringing the rest. pages_loose names the pages no line in the body names.
| Name | Required | Description | Default |
|---|---|---|---|
| as | No | Bring the whole document in standard GitHub Markdown, to hand to another tool — Confluence, Jira, Notion, Linear, GitHub — whose own tools turn it into their format. Not everything travels, and the answer says what this document loses in `left_out`, which you tell the person before publishing: attached files stay in Tisty — `export_doc` writes them into a folder, from where the other place's tool uploads them; diagrams stay mermaid fences, drawn by GitHub, GitLab and Notion but shown as code by Confluence and Jira; links to other documents and tasks become plain words; pens, underlines, icons and folds go as HTML tags some places show as written. A document put away or marked as having had its day says so first. Pages come apart, each read with `as`. It takes no part of the document: no `section`, lines or `chars` | |
| to | No | Last line. Left out, it reads to the end | |
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| from | No | First line, counting from 1 | |
| chars | No | About how many characters to bring. The answer says `next` when there is more | |
| No | The `print` the previous part came with. Needed only alongside `cursor`, so that two halves are known to be the same document | ||
| cursor | No | The `next` a previous answer gave, to carry on from there. It goes with `chars`; on its own it is ignored and the reading starts again from the top | |
| section | No | One heading and everything under it, numbered as `outline_doc` numbers them, from 0 |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive profile, yet the description adds genuinely behavioral detail: the ~12,000 character threshold that silently switches to an outline with `whole` false, incremental paging with `next`, and that `cursor` without `chars` is ignored and restarts from the top. That last point is exactly the kind of non-obvious behavior annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening is front-loaded with scope, but the prose is dense and elliptical ("the `print` it reads at," "the print comes with every answer"), and the key concept of `print` is never defined. Several clauses duplicate what the schema already spells out, so it is longer than the value it adds.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter read tool with no output schema, the description covers the critical paths: default whole read, overflow to outline, part reading, paging continuation, and the markdown export destination caveats (which the schema covers in depth). Remaining gaps are the undefined `print` token and the unexplained `pages_loose`.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage the baseline is 3, and the description mostly restates the schema's own per-parameter text (lines, chars budget, section numbering, print). It does add a little that the schema lacks — the `whole` return flag and `pages_loose` — but `pages_loose` is not in the schema at all and its role is left cryptic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("The text of a document") and immediately scopes it: whole body by default, outline past ~12,000 characters, or a part via section/lines/chars. It distinguishes itself from `edit_doc` and `export_doc` by positioning reading-part as the ordinary flow, though the phrasing "and the `print` it reads at" front-loads an undefined term that fuzzy the opening.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Reading a part is the ordinary way to work" plus the description of the fallback to outline and the sequence section -> chars -> cursor gives clear when-to-use guidance for each mode. It stops short of naming when to prefer a sibling outright (e.g. `outline_doc` for structure only), so there is no explicit exclusion set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remindSet a task to ringAIdempotent
Make a task that is already here ring at a given moment. Adds to whatever it rings at already and never takes one away, so a reminder the person set themselves is safe. read says what it carries before you add. Use it for the appointment that was filed without one, and leave alone what repeats — a routine already comes back on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| at | Yes | When to ring, each as a day and an hour like 2026-08-30T20:00 | |
| task | Yes | The task id |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the write, non-destructive, idempotent profile, and the description adds real behavior beyond that: it is purely additive, never removes an existing reminder, so a user-set reminder survives. That safety guarantee is exactly the context an agent needs before mutating state. It does not say what happens when the task is missing or the time is in the past.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action in the first sentence, then safety, then usage. The prose is conversational ('a routine already comes back on its own') but each sentence carries distinct information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema and strong annotations, this covers purpose, safety, and scope. Remaining gaps are edge-case failure behavior (unknown task id, past timestamps) and what a successful call returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both `task` and `at` are already documented, including the date format. The phrase 'adds to whatever it rings at already' hints that `at` accumulates multiple times, but the description never restates or clarifies the parameter contract beyond that implication.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — make an existing task ring at a given moment — which is clearly distinct from siblings like reschedule, say_done, or plan. It could have named a sibling explicitly (e.g., reschedule vs. remind), but an agent can still tell what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives both a positive case ('the appointment that was filed without one') and a negative case ('leave alone what repeats — a routine already comes back on its own'), plus a pointer to `read` for pre-checking. It stops short of naming the adjacent tool (reschedule) that an agent might confuse this with.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
renameRename a task an agent filedADestructiveIdempotent
Give a better title to a task an agent filed. A task the person wrote keeps its title, opened to agents or not.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The task id | |
| title | Yes | The new title |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable eligibility context: only agent-filed tasks can be renamed, and person-written tasks are unaffected regardless of sharing settings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences and front-loads the core action. The second sentence clarifies the scope restriction efficiently, though the phrase 'opened to agents or not' is slightly indirect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool with rich annotations and full schema coverage, the description provides the key missing context: eligibility based on who filed the task. It does not explain error behavior, but that is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both task and title documented in the input schema. The description does not add format or syntax details beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (giving a better title) and a specific resource (a task an agent filed). It clearly distinguishes agent-filed tasks from person-written tasks, though it does not explicitly differentiate itself from similarly named siblings like reword_step or reword_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-not condition: tasks written by a person keep their title even if opened to agents. That is a strong usage boundary, but it does not name alternatives or explain what to do if the task is not agent-filed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rescheduleMove the day of a task you filedADestructiveIdempotent
Change the date or the deadline of a task an agent proposed, when what you learnt since moves it: the meeting slipped a week, the document arrived early. It reaches only what an agent filed — a day the person set is theirs, and naming one of their tasks is refused. Send null to take a day off. Nothing else about the task changes, and closing it is still never yours.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The day it is to be done, or with a deadline the day the work starts (2026-08-31), or null to take it off | |
| task | Yes | The task's id, as `find` or `propose` gave it | |
| deadline | No | The day it is owed by, only once it passes is the task overdue, or null to take it off |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: ownership boundaries, refusal of person-set tasks, null removal semantics, the fact that nothing else changes, and that closing a task is never allowed. This is consistent with `destructiveHint: true` because rescheduling can overwrite or remove date/deadline values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action, gives concrete examples, then states the ownership boundary and null behavior. Every sentence carries useful meaning, including the closing-task boundary, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the important behavioral facts an agent needs: scope, ownership restriction, null removal, side effects, and what remains unchanged. No return-value explanation is needed because there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains `task`, `date`, `deadline`, and null behavior. The description reinforces that both date fields can be changed and that null removes a day, but adds no syntax, format, or edge-case detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource: change the `date` or `deadline` of a task an agent proposed. It clearly distinguishes this from sibling tools like `propose`, `move`, `tick`, and `plan` by narrowing scope to rescheduling an already filed agent task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: when new information moves the task date, such as a meeting slipping or a document arriving early. It also states a hard exclusion — it only reaches tasks an agent filed, and naming a person's task is refused — plus how to remove a day with null.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
restore_docPut a document back the way it wasADestructive
Undo a write to a document. Changing a passage and replacing a body keep what they replaced, and this puts it back; adding to the end keeps nothing, and neither do the person's own saves. Refused unless the document still reads as that write left it — going back would undo whatever came after — with even_if_more to go back over all of it once you have read the document and know that is what you want. What it puts back is kept in turn, so calling it twice leaves the document where it started, which makes it safe to try. Reach for it the moment a write comes back saying something you did not expect, instead of retyping the document from memory.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title — or a task's id, to put back the assistant's notes on its page as they were before the last write | |
| even_if_more | No | Go back even when the document has been written since the kept body was set aside, undoing that writing too. Only when you know what has happened to it — the refusal without this names the risk, and the person may be what was written since |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: which prior content is retained per write kind, that the call is refused unless the document still reads as the write left it, and that even_if_more forces past that guard at the cost of undoing later writes. It also discloses the surprising reversibility property (a second call unwinds the restore). Minor tension: it calls the operation "safe to try" while destructiveHint=true, though the description supplies the reason (the restore is itself undoable).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and the closing sentence is a clean call to action, but the middle is oblique: "Changing a passage and replacing a body keep what they replaced... adding to the end keeps nothing, and neither do the person's own saves" requires re-reading to decode which cases are restorable. Length is defensible; the syntax is what costs it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the description covers the essentials: what is restored, the conflict refusal, the override, and the reversibility that makes failure recoverable. Remaining gaps are modest — no explicit statement of required permissions or what a success response contains, though it does allude to the refusal message content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are already richer than the prose, so the baseline is 3. The description still earns credit by adding the decision rule for even_if_more ("go back over all of it once you have read the document and know that is what you want") and by framing `doc` as accepting either a document id or a task id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb+resource: "Undo a write to a document," which an agent can immediately map to a reversal operation. It further scopes the operation by write type (passage change, body replacement vs. append and the person's own saves). It never names the sibling write tools (write_doc, edit_doc, append_doc) explicitly, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Reach for it the moment a write comes back saying something you did not expect, instead of retyping the document from memory" gives a clear trigger and points away from the retype-yourself alternative. Preconditions for the forced path are stated: only use even_if_more once you have read the document. It stops short of naming the concrete alternative tools or saying when restore is impossible (append / person's own saves).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reword_noteRewrite a note in a task's journalADestructiveIdempotent
Rewrite a note in the journal of a task you filed or one the person opened to agents, named by the id read shows beside it. The new body replaces the old one whole; a note cannot be emptied.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What the note says now, in the Tisty language | |
| note | Yes | The note's id, from `read` with `journal` | |
| task | Yes | The task id |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare that this is a destructive, non-read-only, idempotent operation. The description adds meaningful behavior beyond the annotations: the new body replaces the old body wholesale, and a note cannot be emptied. It does not describe failure modes or return behavior, but the critical mutation semantics are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the action and resource immediately. Every clause adds relevant scope or replacement semantics, with no obvious filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no output schema, the definition covers the essential context: eligible tasks, note id source, full replacement, and non-empty constraint. It does not explain the response or failure behavior, but the annotations and complete schema cover much of the remaining structured context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter descriptions already carry the baseline. The tool description still adds useful semantics beyond the schema: the task must be one the agent filed or one opened to agents, the note id should come from `read`, and the body fully replaces the existing note content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: rewriting a note in a task's journal. It also scopes the operation to tasks the agent filed or tasks the person opened to agents, and identifies the note by the id shown by `read`. This is enough for an agent to distinguish it from sibling tools such as reword_step or note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear eligibility context: the task must be one the agent filed or one the person opened to agents, and the note id comes from `read`. It does not explicitly name alternatives such as reword_step or note, so it falls short of full when-to-use/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reword_stepRewrite an open stepADestructiveIdempotent
Rewrite a step that is not ticked, on a task you filed or one the person opened to agents. A ticked step is refused: untick it first if the tick was yours by mistake.
| Name | Required | Description | Default |
|---|---|---|---|
| step | Yes | The step, by its text as `read` shows it | |
| task | Yes | The task id | |
| text | Yes | What the step says now, at most 100 characters |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations by disclosing the refusal behavior for ticked steps and the ownership restriction on which tasks are eligible — information the destructiveHint/idempotentHint flags do not convey. It does not describe what the rewrite does to step ordering or what happens to related data, leaving some behavioral surface undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste, with the eligibility scope front-loaded before the failure/remedy clause. Every sentence carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with full schema coverage and no output schema, the description covers eligibility, the main failure mode, and the remedy — enough for correct invocation. It could note whether the rewrite preserves the step's tick state or position, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter is documented (step by its text as `read` shows it, task id, text limited to 100 characters). The description adds no semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Rewrite a step') plus the scope condition ('on a task you filed or one the person opened to agents'), which separates it from siblings like reword_note or rename without requiring the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says a ticked step is refused and routes the agent to `untick` first when the tick was a mistake, giving a clear when-to-use precondition and an alternative. It stops short of contrasting with rename or reword_note, so a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
rulesThe rules for working here, by topicARead-onlyIdempotent
The rules for working in Tisty, one short guide at a time. Left alone it gives the basics — task or document, whose words count, speaking in titles, updating before adding — and an index of the rest. Ask for the guide your next step needs: «tasks» before filing or working a task, «documents» before writing or changing a document, «tidying» before putting things back in order, consolidating or compacting. «all» gives every rule at once.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | tasks, documents or tidying for that guide; all for every rule at once; left out, the basics and the index. general is what all gave before tidying was split off |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the non-obvious default behavior ('left alone it gives the basics... and an index of the rest') and what 'all' returns, which is genuine context beyond the annotations. It does not describe output shape, but a rule-lookup tool has little to warn about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose, then the default, then the topic routing. The prose is slightly ornate ('whose words count, speaking in titles'), but nearly every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single optional enum parameter, a read-only annotation set and no output schema, the description covers default behavior, every topic value and the aggregate option. Only the distinction from the sibling 'help' tool is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and the enum is already documented. The description goes further by attaching a use condition to each enum value ('tasks' before filing, 'documents' before writing, 'tidying' before tidying up), which the schema does not express.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource ('the rules for working in Tisty') and the delivery model ('one short guide at a time'), and enumerates the concrete topics it covers. It is unclear how it differs from the sibling 'help' tool, which it never mentions, so an agent must infer the split.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use triggers tied to each topic: 'tasks' before filing or working a task, 'documents' before writing or changing a document, 'tidying' before consolidating or compacting. It also states the correct behavior when no topic is given, so there is nothing to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
say_doneSay a task is finishedAIdempotent
Say that a task is done, when you did the work yourself — any task of the person's too, since it is only your word. Say it in the turn the work ends. Every step has to be ticked or said done first; with one left it is refused, and so is a whole with a part still open and unmarked. Reading that it no longer matters is not doing it, and goes in say_not_doing. It closes nothing: the task stays open, marked, until the person finishes it or takes the mark off. Say it once; if they have not looked yet, what is new goes in note too.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The account the person reads before deciding: what you did and what makes you sure — the command you ran and what it answered, the commit. In the Tisty language | |
| task | Yes | The task's id, as `find` or `propose` gave it |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the key behavioral twist: this does not close the task; it stays open and marked until the person finishes it or removes the mark. It also describes refusal conditions for incomplete steps/parts and says to call it only once, which adds useful context not captured by the idempotent hint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and constraints are front-loaded, and each sentence carries real behavioral information. The prose is dense and semicolon-heavy, which makes it slightly harder to parse than necessary, but there is little outright filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation-like tool with full schema coverage and no output schema, the description is unusually complete: it covers timing, prerequisites, refusal behavior, non-closing semantics, and the `say_not_doing` alternative. An agent has enough information to invoke it correctly without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both `task` and `body` are already documented in the schema. The description adds task-scope context and a note about what to put in `note` if the person has not looked yet, but it does not add much meaning beyond the schema for the two actual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — declaring a task done — and clarifies the unusual scope: it can mark any task of the person's, but only as your word, not as a close. It explicitly distinguishes the adjacent case that belongs to `say_not_doing`, so an agent can route correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use guidance: say it in the turn the work ends, when you did the work yourself, and only after every step is ticked or said done. It also gives a direct exclusion: reading that something no longer matters is not doing it and belongs in `say_not_doing`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
say_not_doingSay a task should not be doneAIdempotent
Say that a task will not be done — it no longer matters, something else made it moot — on any task, the person's too, since it is only your word. Unticked steps do not stop it. It drops nothing: the task stays open, marked, until the person drops it or takes the mark off. Say it once; what is new after that goes in note.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The account the person reads before deciding: why it should not be done, and what you found that says so. In the Tisty language | |
| task | Yes | The task's id, as `find` or `propose` gave it |
TDQS
A4.1/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: the task is not dropped, stays open and marked, remains until the person removes the mark, and unticked steps do not block the mark. This directly clarifies the non-destructive mutation and persistence semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, and each sentence carries useful information about state, edge cases, or follow-up behavior. Some phrasing is cryptic, especially 'on any task, the person's too, since it is only your word,' but the description is not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with annotations and no output schema, the description covers the key lifecycle and usage details. It is slightly incomplete on what a caller should expect back and leaves one scope phrase ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already explains `task` and `body`. The description does not add parameter-level meaning beyond that baseline, and its reference to `note` points to a sibling tool rather than an input parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and condition: saying a task will not be done because it no longer matters or has been made moot. It is distinguishable from say_done and note, though it does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditions for use ('no longer matters, something else made it moot') and routes follow-up information to `note` rather than repeated calls. It does not explicitly state exclusions or spell out when to use say_done instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sum_upSay what a document is aboutAIdempotent
Leave what you worked out about a document, so the next agent — or you, next week — does not have to read it again to know whether it is the one. A summary of what it says, notes for what somebody working with it should know. Kept on this machine only: it never syncs, it is not part of the document, and the person does not see it. Stored against the text as it reads now, so a later write marks it as describing an older version. Write it after reading a long document, never instead of reading one, and write what the document says rather than what you would like it to say: the next agent will act on this without opening the document.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title | |
| notes | No | What the next agent should know about working with it — which section holds what, what is out of date, what it is missing | |
| summary | No | What the document says and what a reader would come to it for, in a few lines |
TDQS
A4.1/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich context well beyond the annotations: kept on this machine only, never syncs, not part of the document, invisible to the person, and bound to the current text version so a later write marks it as describing an older version. That staleness behavior is exactly the kind of non-obvious trait annotations cannot express, and it does not conflict with destructiveHint=false or idempotentHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the local-only, invisible, version-bound traits are front-loaded, and each sentence carries information. The prose is a touch ornate ('or you, next week') and could be tighter, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter write tool with full schema coverage and annotations, the description covers storage scope, staleness, and writing etiquette thoroughly. It does not say what a successful call returns, a minor gap given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all three parameters well, so baseline 3 applies. The description's gloss on `summary` and `notes` ('what it says' vs 'what somebody working with it should know') largely restates the schema descriptions rather than adding new syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description makes clear this records a `summary` and `notes` about a document for later agents, and explicitly separates it from the document itself ('it is not part of the document'), which distinguishes it from siblings like write_doc or append_doc. The opening framing ('Leave what you worked out about a document') is a bit indirect, but the substance is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit timing ('write it after reading a long document') and an explicit exclusion ('never instead of reading one'), plus content guidance ('write what the document says rather than what you would like it to say'). It never names an alternative tool by name (e.g. read_doc), so it stops just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tagsThe tags already in useARead-onlyIdempotent
Every tag the person already writes, the most used first, with how many times each one appears, in the plain form they are filed under. Capitals and accents decide nothing: #Camión and #camion are one tag. Ask for it before you tag anything and reuse one when the subject really is the same; a second word for something already tagged splits it in two.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: frequency ordering, inclusion of counts, normalization across capitals/accents, and the returned "plain form" — none of which the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what you get and followed by the normalization rule and the directive to call it early. Slight stylistic flourishes ("the person already writes") but no filler that costs comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There's no output schema, so the description must carry return-value meaning — and it does, covering ordering, counts, and normalization. Minor gaps remain (no statement about whether the list is truncated or how large it can get), but nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and spends its words on output semantics instead, which is the right allocation here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states precisely what the tool returns: every tag the user has already used, ordered by frequency, with occurrence counts, normalized to its plain filed form. There's no explicit verb ("list"/"get"), but the resource and payload are unambiguous, and it's clearly distinguishable from siblings like lists or find.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Ask for it before you tag anything and reuse one when the subject really is the same" gives a concrete when-to-use rule, plus the consequence of ignoring it ("a second word... splits it in two"). It doesn't name alternative tools, but no sibling offers tag enumeration, so the routing guidance is effectively complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tickTick the steps you didAIdempotent
Mark steps of a task done when you did them yourself — the moment you did, not at the end. Name each by its text as read shows it; one unknown name and nothing is ticked, and a name two steps share ticks the next one still open. On a task you filed or one the person opened to agents the step is ticked; on any other of the person's it stays unticked, said done, until they take your word. Either way the task stays open until say_done and the person.
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | One step, by its text — the same as `steps` with one entry | |
| task | Yes | The task id | |
| steps | No | The steps you did, each by its text as `read` shows it — capitals, accents and the spaces at either end decide nothing. One of `steps` or `step` has to come with the call |
TDQS
A4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is a non-read-only, non-destructive, idempotent mutation; the description adds far more: atomic failure ('one unknown name and nothing is ticked'), collision resolution ('a name two steps share ticks the next one still open'), and a genuine permission/state model where ticks on tasks you filed or that were opened to agents apply immediately, while on other tasks the step merely reads as done pending the person's confirmation. That is exactly the kind of side-effect and approval detail annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and no sentence is padding, but the whole definition is a single dense run-on chain of em-dashes and semicolons that is hard to parse on one pass. Information density is high while readability suffers; splitting the atomicity and permission rules into separate sentences would cost nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining atomicity, permission-dependent effects, and the still-open-until-`say_done` state. What it omits is what a successful call actually returns and what happens on an invalid task id, so it is strong but not fully closed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so `task`, `step` and `steps` are already documented, including the case/whitespace-insensitivity rule. The description's one addition beyond the schema is that names must be the text `read` shows and how a duplicate name resolves, which is useful but largely restates the schema's own wording. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause names a specific verb and resource — 'mark steps of a task done' — and the closing clause scopes it against `say_done` ('the task stays open until `say_done`'), so an agent can place it in the workflow. It does not explicitly contrast with the `untick` sibling, which is the most obvious confusion risk, so the differentiation is good but not complete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete timing rule with an explicit exclusion: 'the moment you did, not at the end,' which steers behaviour rather than merely describing the tool. It also states the boundary with `say_done`. It never says when to use `untick` instead (correcting a mistaken tick), leaving that inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tongue_docJoin a document to the languages of another, or take it out of its ownAIdempotent
A document told in several languages is several documents, one per language, that the person sees as one with a switch between them; read_doc, outline_doc, docs and find name them under languages. With of, this joins doc to the languages of that document, moving it into the same folder; both have to say their language, in a lang: line of their properties or, for doc, in lang, which is written there. Without of, it takes doc out of its languages and the others stay together. To write a new translation, write_doc with translation_of does it in one call. A page is in the language of its document and joins nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| of | No | The id of a document whose languages it joins. Left out, it is taken out of its own | |
| doc | Yes | The id of the document to join or take out — an opaque name like `q7ntmzbm-0001`, not its title | |
| lang | No | The language `doc` is in, as a tag like `es`, `en` or `pt-BR`, when its properties do not say it |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation/idempotency/safety profile, and the description still adds real behavior: joining also moves the document into the target's folder, a side effect not visible in the schema. It also states the precondition that both documents must declare a language, either in a `lang:` property line or via the `lang` parameter, which explains the failure mode. What's missing is any statement of what happens on a language mismatch or what the call returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is dense and front-loads the conceptual model before the operational detail, and every sentence carries information (the model, the `of` branch, the no-`of` branch, the write_doc alternative, the page exclusion). The first sentence is long and stylistically circuitous, costing a little readability, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter, non-destructive, idempotent reorganization tool with no output schema, the description covers scope, both operational modes, preconditions, side effects (folder move), an alternative tool, and an explicit exclusion (pages). Nothing an agent needs in order to call it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that `of` switches the operation between join and detach, and that `lang` is only needed when the document's own properties don't already declare it — and that the supplied value is written there ('which is written there'), implying a persisted side effect the schema does not mention.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description establishes a specific model (a document is really one document per language) and names both operations: with `of` it joins `doc` to another document's language set, without `of` it removes `doc` from its own. It also distinguishes itself from `write_doc` with `translation_of` and notes that `read_doc`, `outline_doc`, `docs` and `find` are the read-side siblings. The metaphorical 'tongue' framing adds some indirection, but the concrete semantics are recoverable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The when-to-use is fully explicit and branching: 'With `of`, this joins... Without `of`, it takes `doc` out.' It also names the alternative for creating a new translation ('write_doc with translation_of does it in one call') and excludes pages ('A page is in the language of its document and joins nothing'). An agent can pick between this and write_doc without further inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
unplanTake open steps off a taskADestructiveIdempotent
Take off steps that are not ticked, on a task you filed or one the person opened to agents: a step that no longer applies, or one written twice. With to they are not dropped but handed on, added after the steps of the task they belong on. One ticked step among them and nothing is taken off.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | The id of another task you may work on, open and not said done, to add these steps to after its own | |
| step | No | One step, by its text — the same as `steps` with one entry | |
| task | Yes | The task id | |
| steps | No | The steps to take off, each by its text as `read` shows it — capitals, accents and the spaces at either end decide nothing. One of `steps` or `step` has to come with the call |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive annotation, the description explains exactly which steps are removed and adds an important all-or-nothing guard: if any selected step is ticked, nothing is removed. It also clarifies the `to` behavior as handing steps on rather than dropping them, though it does not address permission or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core operation is front-loaded in the first sentence, and the description stays compact. Some phrasing is dense and slightly ambiguous, but no sentence is wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, idempotent operation with a fully described schema and no output schema, the description covers the main effects, the optional transfer behavior, and the ticked-step abort condition. Edge cases such as missing steps or invalid target tasks are not covered, but the essential calling context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all four parameters. The description reinforces the `to` behavior and the ticked-step guard, but it adds little parameter-level syntax or meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: take off steps that are not ticked from a task. It clearly distinguishes the operation from ticking/unticking by saying ticked steps are not removed, but it does not explicitly name the sibling alternatives it replaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete when-to-use conditions (“no longer applies” or “written twice”) and a when-not condition (“One ticked step among them and nothing is taken off”). It does not explicitly route the agent to alternatives such as `move`, `untick`, or `say_not_doing`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
untickTake back a tick given by mistakeAIdempotent
Unmark steps an agent ticked that are not done after all, on a task you filed or one the person opened to agents. On any other of the person's tasks it takes back your word on steps you said were done. Only a tick or a word an agent gave can be taken back: one the person gave is theirs, and naming it unticks nothing. Name each step by its text as read shows it. Unticking closes and opens nothing; the task stays as it was.
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | One step, by its text — the same as `steps` with one entry | |
| task | Yes | The task id | |
| steps | No | The steps to untick, each by its text as `read` shows it — capitals, accents and the spaces at either end decide nothing. One of `steps` or `step` has to come with the call |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the ownership constraint: only agent-given ticks or words can be taken back, and person-given ticks are no-ops. It also clarifies that unticking does not close or open anything and leaves the task as it was. It does not describe error behavior or the response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The key action is front-loaded, and the sentences mostly earn their place by covering ownership rules and side effects. However, the prose is denser and more metaphor-heavy than necessary for a simple untick operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with full schema coverage, annotations, and no output schema, the description covers the main behavioral constraints: who owns the tick, what can be undone, and what does not change. It could be stronger with a sentence on what happens when an invalid or already-unticked step is supplied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents `task`, `step`, and `steps`. The description reinforces that steps are named by their text as `read` shows it, but adds little beyond the schema, which already specifies case, accent, and whitespace handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific inverse action on a specific resource: unmarking steps an agent ticked. It also distinguishes agent-given ticks from person-given ticks, though the repeated use of 'word' as a metaphor makes the distinction slightly less crisp than it could be.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear conditions for use: steps that were ticked by mistake and are not done after all, on tasks filed by the agent or opened to agents. It explicitly excludes person-given ticks, saying naming them unticks nothing, but it does not name a sibling alternative such as `tick`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_docWrite a documentADestructive
Write something to keep and read again — a recipe, a procedure, a reference, a summary; work to do is a task (propose). In the Tisty language (language has it whole): Markdown from elsewhere is turned into it on the way in, the answer says what changed under turned, and only what has no way in is refused, naming it. Left alone it writes a new document; with doc and print it writes an existing one again, whole — pages the body does not name keep their lines, put back at the end — except, when compacting, the pages you marked, which leave the body. To change one passage, edit_doc does it without carrying the whole both ways. Before writing a new one, find: a subject that has a document gets edit_doc, or this with doc and print, not a second document; a title carrying a ticket, a date or «v2» is the sign you are writing one, and a title already taken is refused, naming it. With compact it writes a document back into the living shape the instructions give: needs print, keeps the old body for restore_doc, and the answer gives the size before and after and what was kept back. A document is tagged by writing #word in its own text, for what it is about: six is already a lot, past 64 the rest are dropped, and tags lists those in use.
| Name | Required | Description | Default |
|---|---|---|---|
| doc | No | The id of a document to write again — an opaque name like `q7ntmzbm-0001`, not its title — replacing its body. Needs `print`. Left out, a new document is written instead | |
| body | Yes | The whole document. Its first line becomes its title. Each paragraph goes on one line, however long: in the Tisty language a single newline is a line break, so markdown wrapped at 80 columns reads broken in the middle of its sentences. Nothing checks this on the way in | |
| lang | No | With `translation_of`: the language the body is in, as a tag like `es`, `en` or `pt-BR`, written into its properties | |
| No | The `print` `read_doc` gave you with the text you are working from. If the document has moved on since, nothing is written and you are told to read it again — so the person cannot lose what they wrote while you were thinking | ||
| anyway | No | A new document whose title names the same subject as one already here is refused; this writes it all the same. Only when it truly is another subject | |
| folder | No | The existing folder its subject belongs in, by its name, its whole path or its id. Expected: `docs` says which exist, the `folder` tool makes a new one once the person agrees, and a name no folder has is refused here. Left out, it sits outside them all, and that needs a reason. Writing an existing document again with `doc` and `print` cannot take `folder`: `file_doc` moves one that is already here | |
| compact | No | With `doc` and `print`: this writing puts the document back in order — what holds today, the subject, the decisions, the history — rather than changing what it says. Call `rules` first: it says the order. In one whole write: before it, move what leaving pages hold and mark them; in it, today first, then the subject, the decisions and a history naming every link and file taken out — one lost without a name is refused. Only what Tisty confirms is stated as today; what you only read stays dated and unconfirmed. Refused on a document the person began unless `person_asked`. The window shows the person it was compacted, by whom and when, with one click to undo; until they decide, only one more whole `compact` of yours goes in | |
| page_of | No | The id of the document this one is a page of — an opaque name like `q7ntmzbm-0001`, not its title. The page is named at the end of that document, and where it is named is where it sits; `page_doc` with `after` puts that line somewhere else. A page follows that document everywhere and takes its folder, so `folder` is ignored, and it holds no pages of its own | |
| person_asked | No | With `compact`: the person asked you in this conversation to compact a document they began. Never otherwise | |
| translation_of | No | The id of a document this one says the same as, in another language. It is written as a document of its own beside that one, in its folder, and the person sees them as one document with a switch between their languages. Its language comes from `lang` or a `lang:` line in its properties, and that document has to say its own. One document per language: a language the group already has is refused | |
| keep_compaction | No | Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive annotation, the description discloses that rewriting with `doc` and `print` replaces the whole body, that `print` prevents overwriting silently if the document moved on, that compaction preserves the old body for `restore_doc`, and that tag overuse is truncated. These are meaningful behavioral consequences not supplied by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single dense paragraph with long semicolon chains, nested exceptions, and many backticked internal terms, making it hard to scan despite the useful content. The opening is front-loaded, but the rest is poorly structured and overpacked.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter destructive write tool with no output schema, the description covers creation, overwrite, version-conflict protection, compaction, folder behavior, page relationships, translations, tag limits, and parts of the return information such as `turned` and size before/after. It is unusually complete for an agent deciding how to call this tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so individual parameter meanings are already well documented in the schema. The description still adds cross-parameter workflow constraints, such as `doc` requiring `print`, `compact` requiring `print` and `rules`, `page_of` ignoring `folder`, and translation-language uniqueness, though some of this repeats schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource, "Write something to keep and read again," with examples like recipe, procedure, reference, and summary. It distinguishes documents from tasks by naming `propose`, and distinguishes new-document writes from existing-document rewrites via `doc` and `print`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing: work to do is `propose`; changing one passage is `edit_doc`; before writing a new document, use `find`; folder selection uses `docs`/`folder`; compaction should start with `rules`. It also states when a title is a sign of duplicate subject and when a title collision is refused.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v1.41.1- Added
tongue_doc - Changed
write_doc2 fields changed- added
Input schema / properties / langAdded value: +{ + "description": "With `translation_of`: the language the body is in, as a tag like `es`, `en` or `pt-BR`, written into its properties", + "type": "string" +} - added
Input schema / properties / translation_ofAdded value: +{ + "description": "The id of a document this one says the same as, in another language. It is written as a document of its own beside that one, in its folder, and the person sees them as one document with a switch between their languages. Its language comes from `lang` or a `lang:` line in its properties, and that document has to say its own. One document per language: a language the group already has is refused", + "type": "string" +}
5 tool updates
v1.39.1- Added
edit_table - Added
help - Changed
propose2 fields changed- changed
Input schema / properties / date / descriptionPrevious value: -"The day it is meant to be done (2026-08-31)"New value: +"The day it is meant to be done, or with a deadline the day the work starts (2026-08-31)" - changed
Input schema / properties / deadline / descriptionPrevious value: -"The day it actually runs out (2026-08-31)"New value: +"The day it actually runs out (2026-08-31): only once it passes is the task overdue"
- Changed
read1 field changed- changed
Input schema / properties / fields / descriptionPrevious value: -"Only these parts of it: any of title, status, closed, notice, date, deadline, reminders, tags, source, list, priority, by_agent, via, said_done, said_not_doing, open_to_agents, part_of, parts, description, steps, journal, kept, document. Left out, everything comes. The id always does"New value: +"Only these parts of it: any of title, status, closed, notice, date, deadline, standing, reminders, tags, source, list, priority, by_agent, via, said_done, said_not_doing, open_to_agents, part_of, parts, description, steps, journal, kept, document. Left out, everything comes. The id always does"
- Changed
reschedule2 fields changed- changed
Input schema / properties / date / descriptionPrevious value: -"The day it is to be done (2026-08-31), or null to take it off"New value: +"The day it is to be done, or with a deadline the day the work starts (2026-08-31), or null to take it off" - changed
Input schema / properties / deadline / descriptionPrevious value: -"The day it is owed by, or null to take it off"New value: +"The day it is owed by, only once it passes is the task overdue, or null to take it off"
1 tool update
v1.33.0- Changed
read_doc1 field changed- added
Input schema / properties / asAdded value: +{ + "description": "Bring the whole document in standard GitHub Markdown, to hand to another tool — Confluence, Jira, Notion, Linear, GitHub — whose own tools turn it into their format. Not everything travels, and the answer says what this document loses in `left_out`, which you tell the person before publishing: attached files stay in Tisty — `export_doc` writes them into a folder, from where the other place's tool uploads them; diagrams stay mermaid fences, drawn by GitHub, GitLab and Notion but shown as code by Confluence and Jira; links to other documents and tasks become plain words; pens, underlines, icons and folds go as HTML tags some places show as written. A document put away or marked as having had its day says so first. Pages come apart, each read with `as`. It takes no part of the document: no `section`, lines or `chars`", + "enum": [ + "markdown" + ], + "type": "string" +}
38 tool updates
- First observed
append_doc - First observed
archive_doc - First observed
attach - First observed
catch_up - First observed
describe - First observed
docs - First observed
edit_doc - First observed
export_doc - First observed
file_doc - First observed
find - First observed
flag_doc - First observed
folder - First observed
import_doc - First observed
language - First observed
lists - First observed
move - First observed
note - First observed
outline_doc - First observed
page_doc - First observed
plan - First observed
propose - First observed
read - First observed
read_doc - First observed
remind - First observed
rename - First observed
reschedule - First observed
restore_doc - First observed
reword_note - First observed
reword_step - First observed
rules - First observed
say_done - First observed
say_not_doing - First observed
sum_up - First observed
tags - First observed
tick - First observed
unplan - First observed
untick - First observed
write_doc
TDQS
A3.5/5.0
Scored across 41 tools
Disambiguation3/5
The set contains many adjacent operations: read vs read_doc, note vs reword_note vs append_doc, docs vs find vs catch_up, archive_doc vs flag_doc, and move vs file_doc/page_doc. Long descriptions do draw boundaries, but with 41 tools an agent must repeatedly disambiguate similar resource/action pairs.
Naming Consistency3/5
Most document tools use a _doc suffix, but task tools have no _task suffix, and names mix verbs (propose, tick, move) with bare nouns (language, lists, rules, docs, tags, help, catch_up). The pattern is readable within domains but not consistent enough for a predictable verb_noun convention.
Tool Count2/5
41 tools is heavy for a personal notes/task system, even one with many distinct capabilities. Several adjacent tools (find/docs/catch_up, note/reword_note/append_doc, archive/flag/file/page) push the surface beyond what an agent can comfortably select from.
Completeness4/5
Coverage is broad: documents support create/read/edit/append/restore/archive/import/export/pages/translations/folders, and tasks support propose/read/plan/tick/note/describe/move/remind/reschedule/complete markers. Gaps are mostly deliberate limits (no task close/delete, no list creation), so agents have workarounds but a few lifecycle edges are absent.
Maintenance
ActivityActive
ResponsivenessSyncing
Related MCP Connectors
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Personal context for every AI: search, read, and write back to your private Markdown library.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceLocal Markdown/HTML note-taking app with built-in MCP server, agentic workflow runtime engine, wikilinks, and state-machine approval gates.46 npm1MIT
- AlicenseAqualityBmaintenanceEnables users to create, retrieve, update, delete, and full-text search a local knowledge base of notes persisted in SQLite with FTS5, exposed over stdio or authenticated Streamable HTTP. It also surfaces recent/single-note resources and prompts for summarizing notes and drafting replies.5MIT
- FlicenseNot gradedqualityAmaintenanceEnables users to create timestamped atomic notes in Markdown, bidirectionally link and tag them into a searchable knowledge graph, and explore, synthesize, or discover relationships among ideas through Claude and other MCP-compatible clients. Notes are stored as human-readable files with an SQLite index that supports finding similar, central, and orphaned notes.-