Subroutine MCP tools

The 15 tools the pinned MCP server offers an agent, as its tools/list describes each one.

subroutine_list

List work. Reads only, and changes nothing.

List open items — tasks and documents — from the backlog. Newest first; order='-priority_score' is what to work on next, ranking assessed items above half-assessed above unranked.

Arguments

• assignee (string): Only what is assigned to somebody. 'me' is you.
• filter (object of string): Narrow by when, by whom and by how long: {'created_at.gte': 'yesterday'}; two entries make a range. gt/gte/lt/lte on claimed_at, completed_at, content_updated_at, created_at, due_at, snoozed_until, starts_at, updated_at. estimate_minutes takes '2h' or '90'. importance, urgency are 1-5. assignee, claimed_by, created_by, parent, project, status, tag, type, under take a name, and '.in' takes several separated by commas. answers_to takes a username and reaches their agents' work too. Add '.is' with 'set' or 'unset' to any field that can be empty; takes only that. touched_at is *worked on* — a comment or status change counts, which no other field sees. touched_by takes a username and pairs with it.
• limit (integer): Rows. Default 20.
• order (string): Sort fields, comma-separated, '-' to reverse: '-priority_score', '-due_at', 'title'.
• project (string): Narrow to this project and everything under it.
• ready (boolean): Only work that can be started: nothing unfinished blocks it and it is not deferred. Does not read an item's own status.
• to_act_on (boolean): Yours to act on: assigned to you, or to nobody, or held by you. Wider than assignee=me.
• today (boolean): The agenda: overdue, today, in progress, upcoming, next.
• workspace (string): Workspace name or id.

subroutine_search

Search. Reads only, and changes nothing.

Find items by their words, and terms — 'type:bug deploy'. Tasks and documents both.

Arguments

• limit (integer): Rows. Default 20.
• project (string): Narrow to this project and everything under it.
• q (string, required): Words to look for, and terms — 'type:bug deploy'.
• workspace (string): Workspace name or id.

subroutine_show

Read one item. Reads only, and changes nothing.

Read one task or document in full, with its links and its record. A ref may name either kind.

Arguments

• from (integer): Continue a cut body from this character.
• history (boolean): Every change, newest first.
• ref (integer or string, required): The item's number.
• tree (boolean): What has to happen before this can, all the way down. On a milestone that is its contents.
• workspace (string): Workspace name or id.

subroutine_add

Add a task. Adds or changes, and never deletes.

Create a task from one line. Dates, tags, priority, estimate and repeats ('every other tuesday') are parsed out of it: 'Fix the boiler by friday !4/2 ~2h #home +web'. !importance/urgency are 1-5, ~ is a duration, # is a tag, + is a project. Anything not recognised stays in the title verbatim.

Arguments

• description (string): Why it matters, in full. The title stays one line.
• parent (integer or string): The item this is part of, by its number.
• text (string, required): The line to capture.
• type (string): task, bug, feature, chore, question, event.
• workspace (string): Workspace name or id.

subroutine_comment

Record what happened. Adds or changes, and never deletes.

Add to an item's record of what happened — what you did, what you found, what failed. A '#42' in the body is a reference, not a link — subroutine_show offers the link where one fits. For a conclusion the next session needs, write a document instead. Pass remove=true with words from a comment to take it back out.

Arguments

• body (string, required): What happened.
• ref (integer or string, required): The item's number.
• remove (boolean): Withdraw it instead.
• workspace (string): Workspace name or id.

subroutine_document

Write or revise a document. Adds or changes, and never deletes.

Record a conclusion the next session needs — a decision, a finding, a design, a dead end. A comment is what happened; a document is what you concluded. What you write is in force at once, and what is in force is what subroutine://conventions delivers — give it a status to hold it back while you are still thinking. A '#42' in the body is a reference, not a link — subroutine_show offers the link where one fits. Pass ref to revise one rather than writing a second.

Arguments

• body (string): The reasoning, in Markdown.
• expected_version (integer): Refuse the write if it has changed since you read it. Send the version subroutine_show gave you.
• parent (integer or string): File it under this document.
• project (string): Project key.
• ref (integer or string): Revise this one. Omitted stays.
• status (string): A document status key, e.g. draft — subroutine://meta lists this workspace's own. Omitted puts it in force.
• tags (array of string): Labels, without the '#'. The same tags tasks use.
• title (string): What it concludes, in one line.
• type (string): note, spec, design, decision, finding, dead_end.
• workspace (string): Workspace name or id.

subroutine_update

Change a task.

Change a task: priority, estimate, status, title, or the day it is planned for or hidden until. Set both priority axes — one alone sorts below everything ranked. Omitted fields are unchanged.

Arguments

• applies_to (string): If it repeats: 'this_one', or 'from_now_on' for every one after it too. Required then, refused otherwise.
• assignee (string): Hand it to somebody, by username. '' for nobody.
• defer (string): Hide it until this day, or a time on it. '' to unhide.
• description (string): What it is about, in full. This is where the reasoning behind an outcome-shaped title goes.
• estimate (string): How long, e.g. '4h'.
• expected_version (integer): Refuse the write if it has changed since you read it. Send the version subroutine_show gave you.
• importance (integer): 1-5, 5 highest.
• plan (string): The day to do it. A date or ''.
• ref (integer or string, required): The task's number.
• repeat (string): How often it comes round. '' stops it.
• status (string): A status key, e.g. in_progress.
• title (string): A new title.
• type (string): task, bug, feature, chore, question, event.
• until (string): The last day, if it lasts more than one. A date or ''.
• urgency (integer): 1-5, 5 soonest.
• workspace (string): Workspace name or id.

subroutine_link

Join two items.

Say how two items are related. 'blocks' is what readiness reads — a task with an unfinished blocker is not listed as ready. Pass remove=true to withdraw the link instead.

Arguments

• other (integer or string or array, required): The other item's number, or several of them.
• ref (integer or string or array, required): The item's number, or several of them.
• remove (boolean): Withdraw it instead.
• type (string): A link type key; subroutine://meta lists this workspace's.
• workspace (string): Workspace name or id.

subroutine_project

Projects. Adds or changes, and never deletes.

List the projects, or make one by passing a key and a title. A key is permanent and lower case, like web or web-sales. Work is filed under a project with '+KEY' in a captured line.

Arguments

• key (string): Its permanent short name.
• parent (string): Put it inside this project.
• private (boolean): Only you can see it. POST /v1/projects/{key}/members lets somebody else in.
• title (string): What it is called.
• workspace (string): Workspace name or id.

subroutine_changes

What changed. Reads only, and changes nothing.

What has changed since you last looked, oldest first. Ask at the start of a session: nothing here tells you when your own knowledge went stale. Pass the seq of the last event you saw back as 'since' — it is inclusive, so you will see that one again. For a period rather than a resume, use 'filter'.

Arguments

• filter (object of string): Narrow by when: {'created_at.gte': 'yesterday'}; two entries make a range. gt/gte/lt/lte on created_at.
• limit (integer): Rows. Default 20.
• mine (boolean): Only what this credential itself did.
• since (integer): Resume from this seq, inclusive. Omit for the newest.
• workspace (string): Workspace name or id.

subroutine_journal

What happened. Reads only, and changes nothing.

What happened over a period, with what people wrote and who did each thing. subroutine_changes says what *moved* and is what you resume from a seq; this is the same events joined to the comments, the actor names and what a change moved between. Ask it when somebody wants a period written up. Give it a 'filter' — without one you get the most recent.

Arguments

• by (string): Only what one account did, by name. 'me' is you.
• filter (object of string): Narrow by when: {'created_at.gte': 'yesterday'}; two entries make a range. gt/gte/lt/lte on created_at.
• limit (integer): Rows. Default 20.
• oldest (boolean): Read the period forwards, in the order it happened.
• workspace (string): Workspace name or id.

subroutine_claim

Take a task. Adds or changes, and never deletes.

Take a task so another worker does not start it too, or give one back. 'ready' listings hide what somebody else holds and never hide your own. A claim does not say work has begun: set status to in_progress when you do. A claim expires by itself, so say it again while you are still working.

Arguments

• ref (integer or string, required): The task's number.
• release (boolean): Give it back instead of taking it.
• workspace (string): Workspace name or id.

subroutine_whoami

Who am I. Reads only, and changes nothing.

The account these tools act as, and what it may do. Worth asking before your first write: a shell you run resolves its own credential and can be a different principal, which is silent when it is wrong.

subroutine_call_api

Call the API directly.

For what the tools above do not cover. Prefer them: they carry the conventions this instance expects, and subroutine_add's line grammar (!4/2 ~2h #home +web) is not applied to fields you send here. Read subroutine://meta for this workspace's keys and subroutine://docs/examples for worked calls. Paths are like '/v1/tasks'.

Arguments

• body (object): The JSON body, for a write.
• method (string, required): GET, POST, PATCH or DELETE.
• path (string, required): The route, e.g. /v1/projects.
• query (object): Query parameters, as strings.

subroutine_done

Finish a task. Adds or changes, and never deletes.

Mark a task complete by its ref number.

Arguments

• ref (integer or string, required): The task's number.
• skip (boolean): Let this one of a repeat go by.
• workspace (string): Workspace name or id.