What can you do with this server?

An MCP server for Tisty that lets an assistant manage local tasks and Markdown documents, search across them, and operate within explicit agent permissions. * Propose one or more tasks with titles, dates, deadlines, lists, tags, priorities, steps, parts, reminders, descriptions, and source references. * Read, search, and find tasks and documents, including the archive; catch up on recent changes; inspect lists, tags, and folders. * Work on tasks an agent filed or the user opened to agents: describe, plan steps, tick/untick steps, reword or remove open steps, rename agent-filed tasks, reschedule dates, move lists or parts. * Add and rewrite journal notes on tasks, and mark tasks done or not to be done for user confirmation, without closing or deleting them. * Attach files to tasks or documents from allowed local locations, and manage assistant notes on task pages. * Write, append to, edit, restore, import, and export Markdown documents using Tisty syntax and page structures. * Organize documents with folders, file them, create or reorder pages, archive/restore documents or pages, and flag obsolete documents for the user to delete. * Read, outline, summarize, and search inside documents; maintain machine-local summaries for other agents. * Query Tisty rules and language guides to follow task and document conventions. * Respect boundaries: some operations only apply to agent-filed or agent-opened tasks, and the server cannot close or delete tasks or delete documents.

Tisty

by rgdevment

Overview Schema Source Related Servers Discussions Admin

Rust

Local

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 cat and searchable with grep.
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.

Related MCP server: log-reflect-mcp

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
PDF	its own: A4, Letter or Tabloid, with its pictures inside
Any `.md` file	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	through a folder you already sync. No server of ours
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. If you already sync a folder, Tisty travels through it. 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.

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.
Diagrams from a few lines. A block that says mermaid draws flowcharts, sequences, pies, timelines, mind maps, Gantt charts and more, light or dark with the window.
Formulas set from a math block, code coloured by its language and named after its file, and tables that keep how their columns lean and how wide you drew them.
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 PDF of its own, A4, Letter or Tabloid, with its pictures inside, shown to you before you export it.

Markdown notes, plain files, any editor: formulas and a widget drawn inside a document, with the formatting and the PDF in the column beside 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 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, ![plan](plan-0006bf09.png). 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 Tabloid, 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 wiki.

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.Tisty

macOS — with Homebrew. The tap is added once and never again. After that Tisty keeps itself up to date, so Homebrew stands aside:

$ brew tap rgdevment/tap
$ brew install --cask tisty

Or 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 answers four questions rather than wearing five labels. General is how Tisty behaves towards you — language, start-up, the quick capture, notices, updates, and the one thing that happens outside the window: the welcome. Your data is everything that touches your files, with syncing as a block of its own because it has a state, a warning that depends on who keeps your folder, and four actions. Assistants and Maintenance are what they say.

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 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.

Type it the way you say it: tags, lists, priority, dates and repeats like every tuesday are read from plain words, with the day, the quadrants and the lists counted down the side

"ship the release tomorrow at 10"   →  tomorrow 10:00
"file the report before friday"     →  due fri
"book the flights @travel #urgent"  →  @travel · #urgent

A 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 three words open one: before, 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.

One card for each part of life: tasks grouped by list, each with its own icon and name, beside the task that is open

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.

Decide what matters, then do it: the Eisenhower matrix sorts every task into do, schedule, delegate or minor, with the unclassified pile on the side

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.

Your week, laid out: every task lands on its day, the ones with no day wait on the left, and the month is a switch away

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

Yours, nothing else: Tisto, Tisty's beaver, beside what Tisty never asks of you — no account, no subscription, no telemetry, and your files stay on your computer

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 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. It is written out in PRIVACY.md and SECURITY.md, including the parts that are not reassuring.

Tisty makes one network request unasked — when it opens, and once a day after that: it checks whether a newer version exists. It sends nothing. If one does exist and you press the button that offers it, two more 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.

Two Machines, If You Have Two

Tell Tisty where to leave the copies, in Settings › Syncing. There are two ways, 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 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. Dropbox may come later; nothing is promised.

Before you sign in, 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.

There is nothing of mine in the middle: no account, no server, no daemon. Who runs that folder or that Drive 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.

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.

Each machine signs what it writes, and one nobody here has answered for waits at the door: its card in Settings › Maintenance shows the key it signs with, you compare it with the one that machine shows on its own card, 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.

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 wiki 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

Bring your favourite agents, they do the housekeeping: Settings › Assistants lists the ones installed on this computer and connects each through MCP, with no AI inside Tisty

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> mcp

Where <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 — «by Claude Code», «by Codex» — in the row, the detail and the journal, and 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 Will Never Do

As important as the list above. Permanently out of scope: real-time collaboration, kanban boards, Gantt charts, time tracking, productivity metrics, databases with typed properties and formulas, and AI anywhere in the critical path.

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 the store 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 or OneDrive in the window, and Tisty talks to it directly, keeping its copies in a space of its own there and seeing nothing else. 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? There is no Linux build today. The core is Rust and the window is Tauri, so nothing in the design stands in the way; what is missing is the packaging and somebody to keep it working on the distributions people actually run.

Is my data encrypted? 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. PRIVACY.md writes 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
Obsidian	Windows, macOS, Linux, iOS, Android	Your disk; syncing is a paid extra	Closed source, free for personal use
Logseq	Windows, macOS, Linux, iOS	Your disk	AGPL-3.0
Joplin	Windows, macOS, Linux, Android, iOS	Your disk; syncing through a service you pick	AGPL-3.0
AppFlowy	Windows, macOS, Linux, Android, iOS	Your disk, or a server you pick	AGPL-3.0
Anytype	Windows, macOS, Linux	Your disk, synced encrypted	Any Source Available 1.0
SilverBullet	Self-hosted, in a browser	A server you run	MIT
Super Productivity	Windows, macOS, Linux, mobile	Your disk; syncing through a service you pick	MIT
Taskwarrior	Command line	Your disk	MIT
Things 3	macOS, iOS	Your device; their cloud to sync	Paid, closed source
Craft	macOS, iOS, Windows, Android, web	Their cloud; a local folder gives up sharing	Freemium, closed source
Todoist	Everywhere	Their servers, and an account	Freemium, closed source
Notion	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 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

How the store, the merge and the sync actually work is written down in ARCHITECTURE.md — a reference for the behaviour, not a tour of the code.

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, discussions or the wiki — 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

38 tools

append_docAdd to a document, or to a task's pageA

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
`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.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so well: it says append never rewrites, existing content cannot be lost, no `print` is needed, `echo` returns surrounding lines, and `replace` preserves the replaced content for `restore_doc`. It also discloses task-page behavior including dated, signed assistant notes.

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 append-only guarantee are front-loaded, and the dense sentences mostly earn their place by covering alternatives and task-page behavior. It is long but justified by the tool's complexity, though some phrasing could be tightened.

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 six-parameter mutation tool with no annotations and no output schema, the description is complete enough: it explains the append-only guarantee, heading placement, return behavior (`grew`, `echo`), task-page rules, and `replace` semantics. The only parameter not covered in prose is `keep_compaction`, which is fully described in 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 description coverage is 100% and the schema already explains every parameter in detail. The description adds some workflow context for `under`, `echo`, and `replace`, but it largely restates schema material and does not mention `keep_compaction` at all, 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?

The description gives a specific verb and resource: add to an existing document at the end or under a named heading. It explicitly distinguishes append behavior from `edit_doc` for changed facts and points to `outline_doc` for headings, so an agent can identify the right tool without opening schemas.

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 states when to use append for chronological content such as logs, minutes, and dated task notes, and when not to use it: a changed fact should use `edit_doc`. It also names `outline_doc` as the way to find headings and explains `replace` for task pages, giving explicit alternatives and conditions.

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 backA

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
`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.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: nothing is deleted, no text changes, archived docs still appear in `docs`/`find` unless `scope` says otherwise, a page stays in place greyed and read-only, and restoring wakes pages individually. These are exactly the non-obvious behaviors an agent would otherwise guess wrong.

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?

Behavioral constraints are front-loaded and every sentence carries information, but the closing paragraph about task completion is a lengthier tangent than needed to exclude a sibling. Slightly dense prose with backticked identifiers embedded mid-sentence.

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?

No annotations and no output schema, so the description must cover behavior — and it covers nearly all of it: reversibility, visibility in search, page-level semantics, and folder filing. It stops short of stating what the call returns or any permission/ownership requirement, which is a modest gap for a mutation tool.

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 further by explaining what `archived` false means behaviorally and that restoring wakes each page as it was. It adds some meaning for `doc` (opaque id, not title is in the schema) and notes archive items can still be filed, though it does not elaborate on `folder` beyond the 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?

States a specific reversible operation on a specific resource: putting a document (or one page) away and bringing it back. It also explicitly contrasts with the sibling `flag_doc` for deletion, so an agent can separate the two without reading either 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?

Gives the triggering condition for use, the toggle for the inverse operation (`archived` false), and an explicit alternative for the confusable case («Delete it» is `flag_doc`). It also notes the distinction from task completion, ruling out `tick`/`say_done`.

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": ![name](page-1a2b3c4d.html "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
`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.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: it discloses that the file is copied rather than linked, that doc attachments land at the end, that task attachments record provenance, the 650 MB ceiling for both targets, and the special `.html`/`.htm` widget rendering plus how to opt out via the `"file"` title. That is exactly the non-obvious behavior an agent could not infer from the schema.

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 behavior and the mutually-exclusive destination rule are front-loaded, which is correct. The single dense paragraph stacks several nested clauses around the html widget fallback syntax, making it harder to scan than it needs to be, though nearly every sentence carries real 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 4-param mutation tool with no annotations and no output schema, the description covers destination semantics, size limits, copy-not-link durability, and rendering behavior. What it omits is what the tool returns (a reference string? an id?) and any failure modes beyond the size cap, which an agent would want when chaining follow-up calls.

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 an extra point by explaining what each destination parameter actually produces (task journal entry with source noted vs. appended document element). It does not clarify `label` defaults beyond what the schema already says, so it stops short of 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 concrete verb and action ('Copy a file from this machine into Tisty') plus the two possible destinations, so the resource and scope are unmistakable. It also spells out the divergent outcomes for `task` vs `doc`, which lets an agent distinguish this from sibling tools like `write_doc` or `file_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?

Explicitly says to name `task` OR `doc` and that it is 'One or the other, never both,' which is the key decision the caller must make. It also adds a caution ('Only attach what you were asked to') but never names a sibling alternative for when a file should not be attached this way.

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 movedA

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.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and does so well: it discloses that lists/folders/tags return every call while tasks-touched and documents-written are incremental, and it explains the cursor round-trip. It stops short of stating payload size limits ('how much there is' is undefined), read-only guarantees, or rate limits, which leaves a small gap for a mutation-free but potentially large read.

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', which is the right lead. The second sentence is long and stacked with em-dashes, making it harder to scan than necessary, though every clause carries real 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?

No output schema and no annotations, so the description must describe the return contents — and it enumerates them concretely. It does not describe the shape or nesting of those results, but for a one-optional-parameter snapshot tool this is close to complete.

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 the single parameter is already fully documented in the schema, including the 'what moved since / where things stand comes either way' semantics. The description largely restates that, adding little beyond what structured data already provides — baseline 3.

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 exactly what the call yields (lists, folders, tags, counts, recent documents, cursor) and explicitly positions itself as a replacement for `lists`, `tags` and a blind `docs`. An agent can distinguish it from those siblings 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance: 'the first thing you ask' and 'the thing you ask again when you come back'. It also names the siblings it supersedes, which is the strongest form of routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describeDescribe a taskA

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.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral information itself. It importantly discloses that an existing description is wholly overwritten and advises reading first, though it does not cover permissions, reversibility, or failure behavior.

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 compact and front-loads the core action and overwrite warning. The phrasing is slightly awkward and repetitive, but every clause carries useful 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 simple two-parameter mutation with no output schema, the description covers purpose, overwrite behavior, the read-first prerequisite, and where other information belongs. Only minor edge cases such as task-not-found behavior are left unstated.

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` and `body` are already documented. The description adds some context about which tasks qualify and what `body` should contain, but does not add syntax or format details beyond the schema.

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: writing the description of a task. It also scopes the task to one the agent filed or one opened to agents, and distinguishes the content from `note` by saying learnings go there.

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 usage conditions: use this for tasks the agent filed or that were opened to agents. It names the prerequisite `read` when a description exists and explicitly redirects incidental learnings to `note`, so the agent can choose this tool versus alternatives.

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 foldersA

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
`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.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: default ordering (most recently written first), the exact fields disclosed per document, the subfolder handling ('the answer names them under `below`'), and the repagination loop via `after` and `total`. It stops short of stating permissions or result-size limits beyond the schema's 200/50 default.

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?

Three sentences with the return shape front-loaded, but the phrasing is florid and indirect — 'the `print` of the one you go on to edit' and 'the words it leans on' require decoding — which slows an agent scanning for a listing tool.

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?

No output schema exists, yet the description characterizes the returned record fields and ordering well enough to use results without trial. Given seven optional parameters and folder/archive/scope interplay, it is nearly complete, though the interaction between `folders` and the textual folder listing could be tightened.

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 all seven parameters are already documented, including defaults and enum values. The description adds only the pagination resume pattern and the meaning of `below`, so per the high-coverage baseline a 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 makes clear this returns all documents with per-document metadata (folder, archived state, lock, word/section counts, key terms), and explicitly excludes task-attached notes. It distinguishes itself from read_doc and outline_doc by framing the result as enough to choose a document without opening it.

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 trigger — 'Ask for it before writing, so you do not write again what is already kept' — and routes the agent to read_doc / outline_doc once a document is chosen. No exclusions versus other listing tools like find or lists are stated.

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 documentA

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
`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`
`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?

With no annotations, the description carries the full burden and does it well: prior content is preserved first, the edit is refused rather than partially applied if that fails, concurrent writes cause a no-op with guidance to call outline_doc, and keep_compaction gates a pending compaction. It also warns to sanity-check the returned `grew` delta.

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 core action and the addressing options, and every clause carries information (atomicity, rollback path, grew check). The prose is somewhat baroque ('which let you change a part of a document you never read'), costing a bit of scanability.

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, yet the description explains the return signal (`grew` and the `echo` alternative), the failure modes, and the concurrency guard. For a 9-parameter mutation tool this is comprehensive.

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 cross-parameter meaning: the three mutually exclusive addressing modes and the conflict semantics tied to `print` and the positional fields. It reinforces rather than merely repeats the schema.

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) and immediately enumerates the three addressing modes (old text, section, line range). It clearly differentiates itself from siblings like write_doc/append_doc (partial vs full replacement) and restore_doc (rollback).

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 useful scenario for positional addressing ('change a part of a document you never read') and routes rollback to restore_doc. It does not explicitly state when to prefer write_doc/append_doc instead, so alternatives are implied rather than enumerated.

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 machineA

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?

With no annotations, the description carries the behavioral burden and does well: it discloses markdown output, page ordering, attachment placement, and non-destructive copy semantics. It stops short of covering overwrite/collision behavior, permission requirements, or return/error behavior, 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences are front-loaded with the core output behavior, then the safety guarantee, then the intended usage. Every sentence earns its place with 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?

The description covers the core export behavior and non-destructive guarantee, which is sufficient for a two-parameter tool with full schema coverage. It lacks explicit return/error context and collision handling, so a small gap remains.

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 both required parameters are already documented in the schema. The description does not add syntax or constraints beyond what the schema provides, making the baseline 3 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?

The description states a specific verb and resource: writing a document out as markdown files into a reachable folder, with pages and attachments handled. It distinguishes the operation from in-place editing by emphasizing that an export is a copy and naming the external-handoff use case.

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: hand work to something outside Tisty, and clarifies that nothing changes or is deleted. It does not explicitly name sibling alternatives or state when not to use it, 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.

file_docPut a document, or several, in a folderA

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.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full burden and does disclose real behavior: nothing is deleted, no text changes, and an archived document still moves and remains archived. The archive interaction is exactly the non-obvious detail an agent would otherwise get wrong. What's missing is permission or error behavior for a nonexistent folder.

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 action and the omit-folder rule are front-loaded, which is good. The closing clause, 'that is how something already archived is filed where it belongs', is wordy and restates the preceding sentence rather than adding 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 two-parameter mutation tool with no annotations and no output schema, the description covers the important semantic edges: non-destructiveness and archive-preserving moves. A short note on what happens with an invalid folder name 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%, including the subtle 'omit `folder` to remove from every folder' rule and the all-or-nothing batch semantics of `doc`. The description restates the folder-omission rule but adds nothing about `doc`, and the batch atomicity only appears 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?

States a specific verb and resource: move a document into a folder, or remove it from all folders when `folder` is omitted. That is unambiguous on its own. It never distinguishes itself from the sibling `move` or `folder` tools, so an agent browsing the sibling list cannot tell which filing tool to pick.

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?

Usage is implied rather than stated: you file a document, or you unfile it by leaving out `folder`. There is no explicit 'use this instead of X' guidance, and with a sibling literally named `move` plus a `folder` tool, the boundary is left for the agent to guess.

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 archiveA

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
`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

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full load, and it discloses a lot beyond the schema: hits carry `in` plus the matching `line`, `around` lines are truncated at 200 characters (with `read_doc` to get them whole), documents are not paged while tasks are, and sifting fields silently exclude documents from results. It omits any error or permission behavior, but for a read-only search that is a modest gap.

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 modes are front-loaded in the first clause, and with 17 optional parameters the length is defensible — nearly every sentence carries selection or result-shape information. It is a single dense paragraph of heavily nested clauses, though, which makes it slower to scan than it needs to be.

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 17-parameter, all-optional search tool with no annotations and no output schema, the description covers mode selection, result shape (`in`, `line`, line numbers, section), truncation, and paging semantics (`after`/`total`, `docsTotal`). An agent could call it correctly from this text; only error and permission behavior are 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, but the prose adds cross-parameter meaning rather than restating fields: it explains that the sifting fields can narrow or replace a query, that `source` alone answers a yes/no provenance question, and that `doc` switches the whole result shape. That interaction guidance is not obvious from the schema alone.

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 and both resources — 'Search the tasks — open and archived alike — and the documents' — then distinguishes the three query modes and the `doc` scoped mode. It even names the sibling it can replace ('a past decision often reads without `read`'), so an agent can separate it from `read`, `docs`, and `read_doc` 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit mode selection: words via `query`, sifting fields 'alone or narrowing a query', `source` alone for a provenance check, and `doc` to search inside one document. It also states `query` is 'Not needed when sifting by the fields below', which removes a real ambiguity. It stops short of stating when NOT to use this tool (e.g. full-document retrieval belongs to `read_doc`), leaving one inference.

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 deletedA

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
`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.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so well: it explains that the mark changes nothing about the document content or location, that the person sees it when opening, and that deletion/unmarking remain human actions. It also discloses refusal semantics for already-marked documents and skip-and-name behavior within a batch.

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 first sentence front-loads the core purpose and the rest is information-dense, with each major clause adding behavioral or usage context. The ornate phrasing makes it longer and more indirect 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.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It covers state effects, human-in-the-loop deletion, batch behavior, and refusal semantics, which is substantial for a no-annotation, no-output-schema tool. The only notable gap is that it does not explicitly describe the tool's return/confirmation format beyond implying skipped documents are named.

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 schema already documents doc, body, reason, and instead thoroughly, including enum values and required combinations. The description reinforces the meaning of reason/instead/body but adds little syntax or constraint detail beyond what the schema provides.

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: marking a document as no longer worth keeping, with the explicit framing that this is how deletion is proposed because the agent cannot delete. It distinguishes the tool from siblings by naming archive_doc and by explaining that deleting/removing the mark is done by the person in the UI.

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 examples (duplicate, notes folded into a living document, handover for a retired flow) and explicit exclusions: archive_doc is only for putting away when asked, and actual deletion/unmarking is the person's job. It also explains batching multiple copies into one call and the refusal behavior for already-marked documents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

folderMake a folderA

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
`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/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses idempotent behavior when a same-named folder exists, the surprising deep-search lookup when `inside` is omitted, and that icon/colour changes affect appearance only ('nothing is renamed, moved or deleted'). It is missing return-value expectations and any permission/auth notes, 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-loaded with the core action and sized tightly at four sentences. The second sentence is long and nested, bundling idempotency and the `inside` pitfall together, but every sentence carries useful information and none feel like padding.

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 no annotations and no output schema, the description covers the important behavioral risks: idempotency, surprising lookup scope, appearance-only changes, and domain boundaries. It leaves the success response and error conditions (e.g., invalid icon/color) unaddressed, which is a modest gap given the otherwise thorough coverage.

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. The description adds value beyond it by explaining the consequence of omitting `inside` (global name lookup regardless of depth) and reinforcing that `name` is not a path. That is meaningful semantic guidance rather than repetition.

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 a folder for documents') and adds a domain boundary ('folders hold documents, not tasks; tasks go in lists') that separates it from the task/list siblings. It does not explicitly contrast with the doc-centric siblings (write_doc, file_doc, etc.), so it falls just 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?

Implies when to use it (organizing documents) and gives one explicit exclusion and alternative ('tasks go in lists'). It also supplies a crucial usage warning about omitting `inside`, but stops short of a full when/when-not map or naming the sibling to use for other organization operations.

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
`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.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: source files remain untouched, linked assets are copied and repointed, dangling links are removed, secrets are imported with a warning rather than rejected, and task-page imports have a distinct outcome. These are important behaviors beyond what the schema declares.

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 first sentence establishes the core action, but the description is a dense run-on paragraph with indirect phrasing such as 'turning on the way in what the Tisty language has no word for into what it can say.' Most sentences contain useful information, but the structure makes it harder to scan than necessary.

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 complex import tool with no annotations and no output schema, the description covers the key operational details: conversion, asset handling, link rewriting, source-file safety, secret handling, special task-page behavior, and iteration expectations. It is complete enough for an agent to understand what will happen on import.

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 schema already explains all five parameters in detail. The description adds only that folder and page_of behave like write_doc, which is a small extra signal but does not otherwise deepen parameter semantics.

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: read one markdown file from disk and keep it as a document. It also describes the conversion, asset copying, and link rewriting that distinguish import_doc from siblings like write_doc or read_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?

It gives clear operational guidance: one file per call, walk export folders yourself, and a special rule that a task's page import hands properties to the task rather than creating a document. It does not explicitly compare against write_doc or clearly state when not to use import_doc, but the context is otherwise clear.

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 MarkdownA

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

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of explaining behavior. It discloses that the default result is an index, that `topic` narrows to one part, and that `all` returns the whole guide, but it does not explicitly state that the operation is read-only or describe the response format.

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 reasonably sized but somewhat convoluted and poetic, starting with background about plain Markdown before stating the core behavior. The useful information is present, but the phrasing could be more front-loaded and direct.

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 reference-lookup tool with complete schema coverage and no output schema, the description covers defaults, topic selection, `all`, and language choice. It is largely complete, though it could more explicitly describe the returned guide format.

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 both `topic` and `lang` are already documented in the schema. The description reinforces their purpose — selecting a guide section or language — but adds little beyond the schema's own enum descriptions.

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 that the tool returns Tisty's guide to Markdown extensions, either as an index or a specific topic. It distinguishes this reference material from plain Markdown, though the phrasing is somewhat indirect rather than a direct verb-resource statement.

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 says plain Markdown needs nothing from this tool and directs the agent to use `topic` for the specific syntax being written, with `all` for the whole guide. It does not name sibling alternatives, but the when-to-use and when-not-to-use guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listsThe lists that existA

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

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It implies a read operation and provides the inbox fallback behavior, but does not explicitly state that the call is read-only, what permissions are needed, or the return shape; these are clear gaps for an unannotated tool.

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 short sentences; the resource and purpose are front-loaded, and the inbox constraint earns its place by preventing an invalid 'create list' assumption.

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 zero-parameter, no-output-schema tool, the description gives enough to call it and use the result. It could be more complete about whether returned names include the inbox or how they should be passed to propose, but the core 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?

There are zero parameters, so the schema has nothing to document and the baseline is 4. The description adds no parameter detail, which 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?

States the specific resource (the names of the person's lists) and the immediate purpose (filing a task into one). It is not a tautology of 'lists' and the inbox constraint clarifies scope, though it does not explicitly name sibling alternatives.

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 when to call it — to obtain a list name before filing a task — and warns that lists cannot be created here, with the inbox fallback if none is supplied. It lacks explicit alternative routing, but the context is clear.

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 listA

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
`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?

With no annotations, the description carries the full behavioral burden and discloses authorization scope, mutation effects, and important constraints: one-level nesting, closed tasks taking nothing, and completed/not-doing wholes taking no new parts. It does not describe return values or error handling, but it is substantially more transparent than average for an unannotated 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loads access scope before explaining the two operations and constraints. The phrasing is dense and domain-specific, but every sentence adds relevant information without 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 three-parameter mutation tool with no output schema and no annotations, the description covers the important context: who can use it, what the parameters do, and key edge cases. It lacks detail on return behavior and parameter interaction, but is otherwise complete enough to support 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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially the one-level rule and the distinction between agent-filed and person-filed tasks for `list`, making the parameters clearer in context.

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 tool’s operations: `part_of` hangs a task under another or detaches it, and `list` moves an agent-filed task to a better list. It is specific about the resource and effects, though it does not explicitly name sibling tools as alternatives.

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 usage context, including that the task must be one the agent may work on, and it specifies restrictions such as one-level nesting and closed-task behavior. It does not explicitly compare against alternative tools like `attach` or `plan`, but the conditions and exclusions are well stated.

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.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden well: it discloses that this is an append-only addition, that it refuses on closed tasks, and that it works on tasks authored by the person. It does not cover permissions, rate limits, or what the response looks like, so it stops short of 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?

The core action and its conditions are front-loaded in the first clause, and every sentence carries distinct information (disambiguation, trigger, closed-task rule). Slightly dense and oddly ordered, with the callout aside interrupting the main flow, but 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 append tool with no output schema, the description covers the important edge cases: closed tasks, duplicates, and the callout confusion. Only permissions and return behavior are unaddressed, which is minor at this complexity.

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, including the 'Tisty language' constraint. The description adds no syntax, format, or length guidance 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 (append to a task's journal) and immediately disambiguates from the similarly named callout case, pointing at `edit_doc` for that. An agent can tell this apart from `reword_note`, `write_doc`, or `propose` 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit triggers ('when something new turns up about work that already exists, instead of filing a duplicate'), an explicit exclusion (a closed task takes no note), and the alternative action for that case ('propose it anew'). It also names the sibling to use for the callout meaning.

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 documentA

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

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so the description carries the burden. It discloses output cost, that links persist after archiving, and detailed return fields. It does not explicitly declare read-only safety or error behavior, but the read-only nature is clear from the content.

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?

Content is dense and front-loads the return shape, but it is delivered as one long run-on sentence with nested clauses; the field explanations in the latter half are hard to scan. Adequate but structurally weak.

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 no output schema and no annotations, the description explains the return values in detail and covers when to use it. It is complete enough to call correctly, though the prose could be clearer.

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?

Only one parameter with 100% schema coverage. The schema already explains the opaque id format and that it comes from `docs`; the description adds no additional syntax or constraints for `doc`. Baseline 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?

Describes the exact contents of the outline (headings, spans, character counts, page rows, links, flags) and implicitly distinguishes it from body-reading siblings like read_doc by emphasizing 'a few hundred tokens instead of the bodies.' Not a crisp verb+resource, but an agent can tell what it returns.

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 'Ask for this first when a document is long or when you only mean to change one part of it' and contrasts with reading sections or writing via print. Also frames use before archiving by noting links persist.

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 outA

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 ![Its title](tisty:doc/its-name), 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
`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.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains that pages move with their parent document through folder, archive, and deletion; that pages cannot have pages of their own; that hanging writes a line while taking out writes nothing; and that ordering only rearranges existing lines. It also discloses the exact line syntax and escaping rules.

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 necessary information is present and the first sentence front-loads the core dependency, but the description is a long, dense block with convoluted phrasing and some repetition. It would be easier to use if structured into explicit sections for attach, detach, and order.

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 complex six-parameter tool with no annotations and no output schema, the description covers prerequisites, side effects, ordering semantics, line format, and interaction with sibling tools such as `write_doc`. Nothing essential for correct invocation appears to be 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 description coverage is 100%, so the schema already documents the parameters in detail. The description reinforces the main dependency pattern (`doc`, or `order` with `page_of`) and explains `after`/`before`/`at` behavior, but adds little beyond the schema's own parameter descriptions.

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 specific operations: hanging a document as a page, taking a page out, and ordering pages. It also distinguishes a page from a session/task and from a normal document, so an agent can identify the tool 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?

It clearly says what qualifies as a page and explicitly excludes sessions, reviews, progress, and PR notes, routing those to the task instead. It does not give a full sibling-by-sibling decision tree, but the main when/when-not boundary is explicit.

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.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and usefully states that steps are appended after existing ones. However, it does not explain return behavior, failure modes, or limits beyond the schema's 100-character constraint.

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 compact and front-loaded, stating the action first and then the append/read behavior. Every clause adds useful information without repetition.

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 with no output schema, the description covers eligibility, append ordering, and how to view existing steps. It could say more about return or error behavior, but the core 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 both parameters are already documented in the schema. The description adds the ordering implication ('steps go after the ones already there') but no additional syntax or format detail 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 uses a specific verb and resource: adding a checklist or more of one to a task. It clarifies eligibility ('task you filed or one the person opened to agents') but does not explicitly differentiate from related siblings such as unplan or reword_step.

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 eligibility context for when the tool can be used and points to `read` as the way to view existing steps. It stops short of naming when not to use it or which sibling handles removing or editing steps.

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
`date`	No	The day it is meant to be done (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)
`priority`	No	Only if someone said so. Leave it out otherwise
`description`	No	What you read, in the Tisty language

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discloses real behavior: it auto-tags every task #agent, batching in `tasks` isolates failures ('a bad one does not sink the rest'), `parts` is capped at one level and at most 32, and `again` creates a duplicate only under stated conditions. It does not state what is returned (the task id that `part_of` later needs) or permission/auth constraints.

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?

A single dense paragraph that front-loads the definition and then layers the structural rules (tasks, steps, parts, page, tags). Nearly every clause carries information, though the sentence combining batching with per-item failure tolerance packs two ideas into one and the prose style is 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 14-parameter creation tool with no annotations and no output schema, the description covers the conceptually hard parts (task vs document, steps vs parts vs tasks, when duplication is allowed) that the schema alone would not convey. The remaining gap is that it never says a task id comes back, which matters because `part_of` consumes one.

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 all 14 parameters including the tricky `again`, `parts`, `steps`, and `remind` distinctions are already documented in the schema. The description reinforces a few of them (`title`, steps-vs-parts, batching) but adds no syntax or format detail beyond what the schema provides, 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?

The description opens with a specific verb+resource and immediately defines it against the nearest sibling: a proposal of 'something to do', while 'what will be read again is a document (`write_doc`)'. An agent can tell apart propose vs write_doc vs note without opening either 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?

It gives concrete routing rules: several reads from one thread go in `tasks` (each judged independently), a checklist line is a step, multi-task work with one end goes in `parts` one level deep, and a ticket's reviews/PRs/audits belong to its page and parts rather than documents. It stops short of naming siblings like `plan` or `remind` as alternatives, so it is clear context rather than explicit when/when-not exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

readRead a whole taskA

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, 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.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does well: it describes the returned contents at a high level, explains that `fields` limits the response, and notes that closed tasks return `closed` and a `notice` and are immutable history. It does not cover permissions, error behavior, or limits, 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and every sentence carries relevant information, but it is verbose and relies on idiosyncratic phrasing such as 'grey hints,' 'mending,' and 'what it keeps.' Those metaphors make the description less crisp than it could be, even though the overall structure is logical.

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 whole-task read with no output schema, the description gives a reasonably complete picture of what comes back, including document content and closed-task behavior. It is not exhaustive about response shape or failure modes, but it covers the major things an agent needs to call the 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 already 100%, but the description adds useful meaning beyond the schema: `fields` is framed as the way to retrieve only named parts and to inspect one thing without pulling a long journal. It also connects `part_of` to the sibling `find` behavior, giving the parameter practical context.

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 frames the tool as returning everything held by one task, including description, steps, journal, parts, kept items, and document. It is more specific than the generic name `read` suggests and helps distinguish the whole-task read from `find` by noting that `find` with `part_of` retrieves parts of any 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?

It explicitly says to use this before adding a note and before mending anything, and explains the `fields` option for checking one thing on a task with a long journal. It also names `find` with `part_of` as the alternative for retrieving parts across tasks, so when to use this versus another tool is clear.

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 oneA

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
`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
`print`	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.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full load and does so substantially: it discloses the ~12,000-character truncation threshold, the `whole=false` signal, the `print` token returned with every answer that lets a passage be edited without re-reading, and the conversion losses reported in `left_out` when `as: markdown` is used (attachments, mermaid fences, flattened links, HTML formatting). The cryptic 'pages_loose names the pages no line in the body names' sentence is unexplained and reads as opaque jargon.

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?

About 130 words, front-loaded with the whole-document behavior before paging, and each sentence covers a distinct mode or caveat. The final `pages_loose` sentence is an unexplained fragment that a reader cannot place, but otherwise there is little padding.

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 eight-parameter, no-annotation, no-output-schema read tool, the description covers the essential return signals (`whole`, `next`, `print`, `left_out`) and the paging workflow. What is missing is an explanation of what `pages_loose` is and where it appears, plus any note on permissions or failure modes for an inaccessible document.

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 schema already documents all eight parameters — including the doc-id-is-not-a-title note and the cursor/print pairing — and the prose largely restates it. The one piece of genuine cross-parameter insight, that a lone `cursor` is ignored and reading restarts from the top, also appears in the schema. Baseline 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 opening states a specific verb and resource ('the text of a document') and immediately frames the two modes — whole body vs. a `section`, line run, or `chars` budget. It distinguishes itself from siblings by naming `edit_doc` for changes and `outline_doc` for section numbering. The undefined token '`print`' and the dangling 'pages_loose' clause keep it from being fully crisp.

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 concrete when-to-use guidance: called plain it returns the whole body, past ~12,000 characters it returns an outline with `whole` false, and then you page with `section`/`from`-`to`/`chars`. It even prescribes the normal workflow ('Reading a part is the ordinary way to work') and points at `export_doc` for attached files. No explicit statement of when NOT to call this in favor of `outline_doc` or `find`.

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 ringA

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?

With no annotations, the description carries the full disclosure burden and does it well: it states the operation is purely additive ("never takes one away"), reassures that user-set reminders survive, and points at `read` as the way to inspect existing reminders first. It doesn't cover idempotency for duplicate times or what the call returns on conflict.

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, then the safety guarantee, then the usage rule. The final clause is slightly elliptical but each sentence carries distinct 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 two-parameter mutation tool with no annotations and no output schema, the description covers mutation semantics, reversibility/safety, and the read-before-write pattern. A note on duplicate handling or the response shape 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% and the schema already explains both `task` (task id) and `at` (array of day+hour timestamps). The description adds no format or constraint detail beyond what the schema states, so the baseline 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?

Names a concrete verb and resource ("Make a task... ring at a given moment") and scopes it to tasks that already exist, which separates it from creation-style siblings like plan or propose. It stops short of naming a specific alternative tool it should not be confused with.

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 positive case ("the appointment that was filed without one") and an explicit exclusion ("leave alone what repeats — a routine already comes back on its own"). Clear context, but it references siblings only obliquely via `read` rather than by tool name for the add-vs-modify decision.

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 filedA

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.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses the important restriction that person-authored tasks cannot be renamed, but it does not describe permissions, failure behavior, idempotency, or what the operation returns.

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 short sentences with no waste. The core action is front-loaded and the important scope restriction follows immediately.

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 with no output schema, the description covers the essential purpose and the critical restriction on agent-filed versus person-authored tasks. It is nearly complete, though it could add a brief note about error behavior or prerequisites.

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 both parameters are already documented as the task id and the new title. The description adds no syntax, formatting, or validation detail 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 clearly identifies the action as giving a task a new title and the target as a task an agent filed. It is specific about the resource and scope, though it does not explicitly name any sibling tool such as reword_step or reword_note as an alternative.

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 provides a clear usage condition: only tasks filed by an agent can be renamed, while tasks written by a person keep their title regardless of whether they are opened to agents. It does not state alternatives for renaming steps or notes, but the key when-to-use and when-not-to-use rule is explicit.

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 filedA

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
`date`	No	The day it is to be done (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, or null to take it off

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden and does it well: it discloses the authorization boundary (agent-filed only, person-set days refused), the null semantics ('Send null to take a day off'), the blast radius ('Nothing else about the task changes'), and a durable constraint ('closing it is still never yours'). That is exactly the side-effect and permission context an agent needs before a mutation.

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 sentences, front-loaded with purpose, then scope refusal, then null handling and non-effects. Every clause carries information; the illustrative examples ('the meeting slipped a week') are short and earn their place.

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 mutation with no annotations and no output schema, the definition covers who is affected, what is refused, and what is left untouched. It does not say what comes back on success or what happens when the named task doesn't exist or is already 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 description coverage is 100%, so the schema already documents task id and the date/deadline format including null. The description reinforces the null behavior but adds no new syntax or constraints, so baseline 3 is right.

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 set and resource: change the `date` or `deadline` of a task, and names the exact field names from the schema. It also delimits the object ('a task an agent proposed'), which separates it from sibling `move` and from `propose`/`plan` without the agent needing to open either 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 a concrete trigger ('when what you learnt since moves it: the meeting slipped a week, the document arrived early') and an explicit exclusion ('a day the person set is theirs... is refused'). It never names a sibling by name, so an agent that wants to move something else (e.g. `move`) must infer the boundary itself.

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 wasA

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

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so well: it distinguishes which write types are recoverable (passage edits, body replacements) from those that are not (appends, the user's own saves), states the refusal condition and its risk rationale, and notes that repeated calls are idempotent so it is 'safe to try.' This is exactly the mutation semantics an agent needs.

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 key action is front-loaded, but the body is a dense, em-dash-heavy run-on that mixes reversibility rules, refusal conditions, escalation, idempotency and usage trigger into nearly one breath. The metaphorical language costs comprehension relative to a short bulleted statement of the same facts.

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 no annotations and no output schema, the description covers recoverability, blocking conditions, the override, idempotency and the calling trigger. Return values need not be explained given no output schema exists; only the shape of a refusal is left partially implicit.

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 adds the context that even_if_more overrides a refusal and may undo the user's own later work, but that risk is also spelled out in the parameter's own schema description, so most of this is restatement.

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 specific verb+resource: 'Undo a write to a document,' which clearly separates it from write_doc, edit_doc, append_doc and archive_doc. The rest of the description reinforces the restore semantics, though the metaphorical phrasing ('kept body set aside') blurs the core statement somewhat.

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 an explicit trigger ('the moment a write comes back saying something you did not expect') and a stated alternative to avoid ('instead of retyping the document from memory'). It also documents the refusal precondition and the even_if_more escalation path, but never names the sibling tool an agent should use instead.

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 journalA

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
`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

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does disclose two important traits: the new body replaces the old one wholesale (destructive overwrite of the prior text) and a note cannot be emptied (a validation constraint). It omits what happens on an unknown note id, whether the rewrite requires the note to be yours, and whether the change is reversible.

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?

Two sentences, front-loaded with the action and scope, then the replacement and non-empty rules. The middle clause ('or one the person opened to agents, named by the id `read` shows beside it') is dense but carries real 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 an unannotated three-parameter mutation with no output schema, the description covers ownership scope, whole-body replacement, and the non-empty rule — enough to call it correctly. Return behavior and permission-failure handling are the remaining gaps.

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 all three parameters are already documented, including the `read` with `journal` provenance for `note` and the 'Tisty language' constraint on `body`. The description largely restates the same id-source hint, adding 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.

Purpose4/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 note in the journal of a task') and scopes it to notes the agent filed or the person opened to agents, which separates it from reword_step. It never names a sibling explicitly, so the distinction 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 Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an implicit precondition (only notes you filed or that were opened to agents) rather than a when-to-use rule. It does not contrast with `note`, reword_step, or doc-editing siblings, leaving the agent to infer from context.

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 stepA

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
`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/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden, and it delivers the two most consequential behaviors: an authorization scope (only certain tasks) and a hard failure mode (ticked steps are refused) with a remedy. It does not say whether the prior text is recoverable or what a successful rewrite returns, leaving some gaps.

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, and the precondition is front-loaded ahead of the exclusion rule. 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 three-required-parameter mutation with no output schema, the description covers preconditions, authorization, and the refusal path. It stops short of describing success behavior or how ambiguous duplicate step text is resolved.

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 all three parameters are documented there, including the 100-character limit and that `step` is addressed by its text. The description only restates the eligibility constraint rather than adding syntax or format meaning, so baseline 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?

States a specific verb (rewrite) and resource (a step), scoped to unticked steps on a task you filed or that was opened to agents. The resource is clearly distinct from siblings like reword_note, tick, and untick, though no sibling is named to sharpen the boundary.

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 gives the condition for use (unticked step, on a task you own or one opened to agents) and the condition against it (ticked steps are refused). It even routes the agent to `untick` as the remedy when the tick was a mistake, which is a real when-not path.

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 topicA

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.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does a good job explaining the default response (basics plus index) versus topic-specific guides and «all». It does not mention side effects or rate limits, but this is clearly a read-only informational tool and the response shape is described adequately.

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 front-loaded with the core behavior and then lists topic-specific guidance. It is slightly verbose but every sentence contributes to explaining the default mode, topic choices, or the «all» option.

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 single optional enum parameter with no output schema and no annotations, the description fully covers default behavior, each topic's purpose, and the aggregate «all» option. 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?

Schema coverage is 100% and the enum values are already documented in the schema. The description adds workflow meaning by tying each topic to a moment of use, going beyond the raw enum definitions.

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 that the tool returns rule guides for working in Tisty, either as a default basics-plus-index response or as topic-specific guides. It is specific about the resource (rules/guides) and the topic-based access pattern, but it does not explicitly distinguish itself from nearby read/describe/help siblings.

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 workflow conditions for each topic: use «tasks» before filing or working a task, «documents» before writing or changing a document, and «tidying» before reorganizing or compacting. It also states what happens when the topic is omitted, leaving little ambiguity about when to call it.

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 finishedA

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.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so: it discloses refusal when a step remains open, clarifies that the task stays open and marked rather than closed, and says to call it once. These are exactly the side effects and constraints an agent needs.

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 front-loaded with the action, then adds prerequisites, refusal behavior, state effect, and alternatives. Every sentence contributes operational information, 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 two-parameter tool with no annotations and no output schema, the description covers purpose, timing, prerequisites, refusal, state persistence, and sibling routing. It is complete enough for correct invocation.

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 in the input schema. The description does not add syntax or format detail for `task` or `body`; baseline 3 is appropriate when the schema does the parameter-level work.

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: saying a task is done, with the key caveat that it marks rather than closes the task. It distinguishes the operation from `say_not_doing` and `note`, so an agent can identify its role 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 explicit timing (in the turn the work ends), scope (tasks you did yourself or the person's tasks), prerequisites (all steps ticked or said done first), refusal conditions, and an alternative (`say_not_doing` for reading that no longer matters). This leaves little to inference.

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 doneA

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

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: it discloses that nothing is dropped, the task stays open and marked, unticked steps don't block it, and the claim is advisory ('only your word'). What's missing is how the mark is removed or what the person sees on their side.

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 its non-destructive nature are front-loaded, and every sentence carries information. The folksy phrasing ('since it is only your word', 'takes the mark off') costs some clarity but not much length.

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 tool with no annotations and no output schema, the description covers purpose, side effects, scope, and repeat-use behavior adequately. Only the downstream visibility of the mark and its removal path are left implicit.

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 in the schema. The description adds only marginal semantics — scope ('on any task, the person's too') and the repeat-use rule — without new detail on `body` or `task` beyond what the schema provides. Baseline 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 names a specific verb and resource — declaring a task won't be done — and clarifies that this is a statement, not a state change. It implicitly contrasts with `say_done` and explicitly routes follow-ups to `note`, but never names `say_done` or `unplan` as the counterpart, so sibling 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?

It gives a clear trigger ('it no longer matters, something else made it moot') and an explicit alternative for later information ('what is new after that goes in `note`'). The one-shot rule ('Say it once') is a real usage constraint. It stops short of stating when to prefer `say_done` or `unplan` 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 aboutA

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
`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/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and largely does: it discloses that the value is local-only and never syncs, that it is not part of the document, and that the person does not see it — non-obvious traits an agent cannot infer elsewhere. It also explains the staleness mechanic: stored against the current text, so a later write marks it as describing an older version.

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 front-loaded with the purpose, but the prose is long and meandering for a three-parameter store operation, with several repeated cautions (not part of the document / person does not see it / read it first). The value is there, but the sentences are not maximally economical.

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 local write with no annotations and no output schema, the description covers what the data is, where it lives, who can see it, when it goes stale, and how to write it. No return-value description is needed since there is no output schema, and the only minor gap is whether an existing summary is overwritten or merged.

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 defines `doc`, `summary`, and `notes`. The description reinforces the distinction between summary and notes and the fact that `doc` must be the id not the title, but adds no syntax or format beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 act — recording what you worked out about a document so it need not be re-read — and distinguishes the two payloads: `summary` for what it says, `notes` for what someone working with it should know. It is clear enough to separate from `note`, `reword_note`, or `describe`, though the verb is metaphorical ("leave what you worked out") rather than a direct "store a summary on a document", which costs it a point.

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 when/when-not: "write it after reading a long document, never instead of reading one", plus a content rule (write what it says, not what you'd like it to say). That is real routing guidance. It stops short of naming siblings, so it doesn't reach the top score.

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 useA

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.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does well: it discloses ordering (most used first), counts per tag, and normalization rules (capitals and accents are ignored). It does not explicitly state that the operation is read-only or describe pagination/limits, 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core behavior, followed by normalization rules and actionable usage advice. Every sentence contributes to understanding or correct use, and there is no redundant 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?

For a simple zero-parameter tool with no output schema, the description supplies the essential return shape: all tags, usage counts, ordering, and normalized form. It also gives enough usage context to prevent duplicate tag creation, making the definition complete for this tool's complexity.

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 has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and adds useful context about what the no-argument call returns.

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 identifies the resource and scope: every existing tag, ordered by usage, with occurrence counts, in normalized plain form. It does not explicitly name or contrast against sibling tools such as lists or find, which keeps it just short of 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 timing and reuse guidance: ask for it before tagging anything and reuse an existing tag when the subject really is the same. It does not name alternative tools or describe when another sibling would be preferable, so it falls 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.

tickTick the steps you didA

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
`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

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does unusually well: it discloses all-or-nothing validation ('one unknown name and nothing is ticked'), duplicate-name resolution ('ticks the next one still open'), and a permission gate where ticks on tasks the agent didn't file stay 'said done' pending the person's confirmation. It omits consequence/reversibility detail and any response shape, which keeps it off 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded, which is right, but the remainder is dense em-dash prose with elliptical constructions ('said done, until they take your word') that cost the reader more than the content warrants. Several clauses could be split into short declaratives without losing meaning.

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 mutation tool with no annotations and no output schema, the description covers atomicity, duplicates, permission gating, and the relationship to `say_done`. What's missing is what the call returns and whether re-ticking an already-ticked step is a no-op.

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 above that by explaining semantics the schema cannot: one bad name voids the whole call, and a name shared by two steps resolves to the next open one. The `read`-text formatting rule is essentially restated from the schema, so it's not pure added value.

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: mark steps of a task done, naming each by the text `read` shows. It distinguishes itself from `say_done` ('the task stays open until `say_done`'), but never names the obvious sibling `untick` as the inverse operation, 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit timing guidance — 'when you did them yourself — the moment you did, not at the end' — which is real when-to-use context an agent would otherwise get wrong. It stops short of stating when NOT to tick or pointing at `untick` for corrections.

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 taskA

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
`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

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does real work: steps are removed only if un-ticked, the whole batch aborts if any step is ticked, and supplying `to` converts deletion into relaying the steps onto another task. It doesn't cover auth requirements, behavior on unmatched step text, or whether the operation is idempotent.

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 and only three sentences, each carrying a distinct rule. Some phrasing ('one the person opened to agents') is dense enough to slow parsing, but nothing is redundant.

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 no annotations and no output schema, the description covers scope, the abort condition, and the `to` variant. It leaves open what happens when a named step isn't found or what the caller gets back, which matters for an agent verifying the call.

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 an extra point by explaining what `to` actually does semantically (steps are handed on and appended after the target task's own steps rather than dropped), which the schema only hints at.

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: taking un-ticked steps off a task, with the scope of which tasks qualify (ones you filed or that are opened to agents). An agent can tell this removes steps rather than completing them. It stops short of naming the close siblings it might be confused with (untick, plan, move).

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 concrete triggering conditions ('a step that no longer applies, or one written twice') and an explicit exclusion ('One ticked step among them and nothing is taken off'), which tells the agent when this call will be a no-op. No alternative tool is named for the ticked-step or relocation case, so it falls short of full when/when-not/alternatives guidance.

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 mistakeA

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
`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

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the disclosure burden, and it does state important behavior: unticking opens/closes nothing and the task stays as it was, and naming a person-given tick unticks nothing. It omits return/error details and whether already-unticked steps are safely idempotent, 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?

The purpose is front-loaded and every sentence adds relevant nuance about scope, restrictions, or side effects. It is somewhat dense in prose, and phrasing like 'one the person gave is theirs' could be crisper, but it is appropriately sized for the behavioral 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 no annotations, no output schema, and complete parameter schema coverage, the description covers task scopes, eligibility restrictions, no-op behavior for person-given ticks, and the absence of task-state side effects. It leaves response/error behavior and already-unticked handling implicit, which is a modest 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 description coverage is 100%, so the schema already documents task, step, steps, and the text-matching rules including capitals, accents, and spaces. The description reinforces 'text as read shows it' but adds little beyond what the schema already provides, 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 specific verb and resource: 'Unmark steps an agent ticked' / untick. It scopes the operation to tasks the agent filed or the person opened to agents and explicitly excludes person-given ticks, which is enough to distinguish it from tick and related sibling tools 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?

Provides clear when-to-use conditions (agent-ticked steps on eligible tasks) and when-not conditions (person-given ticks cannot be taken back). It does not explicitly name tick as the alternative for marking work done, so it falls short of full alternative-routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_docWrite a documentA

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
`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
`print`	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
`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.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and discloses important traits: Markdown is converted into the Tisty language, unconvertible content is refused with its name, `print` prevents overwriting concurrent changes, duplicate titles are refused unless `anyway`, and `compact` preserves the old body for `restore_doc`, exposes undo, and limits further compactions.

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?

The description is a single dense paragraph with long, nested clauses and parenthetical asides, making it hard to scan. The content is valuable, but the structure is not front-loaded for quick understanding of the several distinct modes.

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 9-parameter mutation tool with no annotations or output schema, the description covers creation, rewriting, compaction, folder and page placement, tagging, and key response fields such as `turned` and `size`. Some operational details remain implicit, but the core behavior is well covered.

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 still adds meaningful mode semantics beyond the schema: `doc` and `print` must be used together for rewrites, `compact` requires `print`, `page_of` ignores `folder`, and `person_asked` / `keep_compaction` are constrained to prior conversation.

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 ('Write something to keep and read again') and explicitly distinguishes it from `propose` for work to do and `edit_doc` for changing one passage. It also distinguishes creating a new document from rewriting an existing one with `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?

Gives explicit when-to-use guidance: run `find` before writing a new document, use `edit_doc` for a single passage, use `doc` plus `print` to rewrite an existing document, and use `compact` with `print` to reorganize. It also names alternatives like `file_doc` for moving a document and `page_doc` for placing pages.

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.

1 tool updatev1.33.0Oct 24, 2026

Changedread_doc1 field changed

addedInput schema / properties / as

Added 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 updatesOct 23, 2026
- First observedappend_doc
- First observedarchive_doc
- First observedattach
- First observedcatch_up
- First observeddescribe
- First observeddocs
- First observededit_doc
- First observedexport_doc
- First observedfile_doc
- First observedfind
- First observedflag_doc
- First observedfolder
- First observedimport_doc
- First observedlanguage
- First observedlists
- First observedmove
- First observednote
- First observedoutline_doc
- First observedpage_doc
- First observedplan
- First observedpropose
- First observedread
- First observedread_doc
- First observedremind
- First observedrename
- First observedreschedule
- First observedrestore_doc
- First observedreword_note
- First observedreword_step
- First observedrules
- First observedsay_done
- First observedsay_not_doing
- First observedsum_up
- First observedtags
- First observedtick
- First observedunplan
- First observeduntick
- First observedwrite_doc

Deploy Server

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored 2026-10-24 16:00 across 38 tools

Disambiguation4/5

Tools mostly target distinct resources and actions, with clear separation between task and document operations. Some subtle overlaps exist, such as note vs append_doc on task pages and find vs docs for discovery, but the verbose descriptions generally clarify the intended use.

Naming Consistency3/5

Document operations often use a _doc suffix (read_doc, write_doc, edit_doc), but the set mixes verb-only (tick, move, propose), noun-only (docs, folder, lists), and verb_noun (say_done, catch_up) patterns. There is no task-specific suffix, making the overall convention uneven despite being readable.

Tool Count2/5

With 38 tools, the surface far exceeds the recommended 3–15 range for a well-scoped server. While the domain is broad, many task-step operations (tick, untick, reword_step, unplan, say_done, say_not_doing) could likely be consolidated, making the toolset feel heavy.

Completeness4/5

The server covers task and document lifecycles extensively, including creation, reading, editing, archiving, import/export, and workspace discovery. Intentional omissions like deletion are clearly handled by flagging tools, leaving only minor gaps such as a straightforward bulk task listing.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

Related MCP Connectors

Pinpal NotesOAuth
com.mypinpal
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Note Taking File Systems
1
https://notes.mypinpal.com/mcp
Very Simple NotesOAuth
com.verysimplenotes
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Note Taking File Systems
1
https://verysimplenotes.com/mcp
ValtaOAuth
si.valta
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Note Taking Knowledge & Memory
1
https://valta.si/mcp
sensefold AOAuth
app.sensefold
Personal context for every AI: search, read, and write back to your private Markdown library.
Knowledge & Memory Note Taking Search
1
https://api.sensefold.app/mcp

Related MCP Servers

Notes — local markdown
Note Taking Knowledge & Memory Search
Abhishekkumar2021
A
license
Not graded
quality
C
maintenance
Local markdown notes for any MCP client: ranked + semantic search, tags, todos, a wiki-link knowledge graph, daily notes, templates, and slash-command workflows. Pure-JS, local, no API keys.
Updated 4 months ago (2026-07-04 21:33 UTC)
4 npm
1
MIT
log-reflect-mcp
Note Taking Knowledge & Memory
sunling
A
license
B
quality
B
maintenance
Captures and retrieves Markdown records for a personal recording system, enabling journaling, input tracking, search, and date-range review.
Updated 6 days ago (2026-10-21 00:05 UTC)
4
1
MIT
Noted
Note Taking Autonomous Agents
fabriziosalmi
A
license
Not graded
quality
A
maintenance
Local Markdown/HTML note-taking app with built-in MCP server, agentic workflow runtime engine, wikilinks, and state-machine approval gates.
Updated 5 days ago (2026-10-22 00:28 UTC)
10 npm
1
MIT
kb-mcp-server
Note Taking Knowledge & Memory Search
venkateshds2u
A
license
A
quality
B
maintenance
Enables 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.
Updated a month ago (2026-09-13 02:06 UTC)
5
MIT

Table of Contents

Why I Built This

What It Is / What It Isn't

What Makes It Different

Documents

Who Is This For?

The Idea It Is Built On

Getting Started

What It Does

Your Data and Privacy

Two Machines, If You Have Two

An Assistant, If You Use One

What It Will Never Do

FAQ

Alternatives

Localization

Other Tools by the Same Author

Support the Project

Standing On

Contributing

Licence

Other terms

Project health

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers