Thogit Tools

Thogits are the core entities in the system. These tools handle creating, reading, updating, deleting, and searching thogits.

add_thogit

Create a new thogit with optional tags and field values.

Parameters

Name	Type	Required	Description
name	string	Yes	Thogit name
description	string	Yes	Thogit description
tags	array	No	Tags to apply, each with tag_ref and optional field_values

Each tag entry has:

Name	Type	Required	Description
tag_ref	object	Yes	{"New": {name, fields, ...}} or {"Existing": "ULID"}
field_values	object	No	Field values to set. Omitted fields default to null.

Field Value Formats

Schema Type	Value Format	Example
String	"text"	"hello"
Number	42	3.14
Boolean	true / false	true
Date	"YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS"	"2025-01-15"
Reference	"ULID"	"01JEXAMPLE0000000000THOGIT"
Select (no data)	{"variant": "name"}	{"variant": "todo"}
Select (with data)	{"variant": "name", "data": value}	{"variant": "blocked", "data": "waiting on review"}
MultiSelect	["a", "b"]	["bug", "feature"]
Null / unset	null or omit

Example

// Request — create a thogit with an existing tag
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_thogit",
    "arguments": {
      "name": "Implement user authentication",
      "description": "Add login/logout with session cookies and OAuth support",
      "tags": [
        {
          "tag_ref": { "Existing": "01JEXAMPLE00000000000TAGID" },
          "field_values": {
            "status": { "variant": "todo" },
            "priority": 8,
            "due": "2025-02-01",
            "labels": ["feature"]
          }
        }
      ]
    }
  }
}

// Response — returns the full thogit with resolved tags
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE0000000000THOGIT\",\n  \"name\": \"Implement user authentication\",\n  \"description\": \"Add login/logout with session cookies and OAuth support\",\n  \"tags\": [\n    {\n      \"tag\": { \"id\": \"01JEXAMPLE00000000000TAGID\", \"name\": \"Task\", ... },\n      \"field_values\": { \"status\": { \"variant\": \"todo\" }, \"priority\": 8, \"due\": \"2025-02-01\", \"labels\": [\"feature\"] },\n      \"schema_version\": 1\n    }\n  ],\n  \"created_at\": \"2025-01-15T10:00:00Z\",\n  \"updated_at\": \"2025-01-15T10:00:00Z\"\n}"
      }
    ]
  }
}

Tip

You can create a new tag inline by using {"New": {"name": "MyTag", "fields": {"field1": "String"}}} as the tag_ref. The tag is created automatically.

---

get_thogit

Get a single thogit by its ID.

Parameters

Name	Type	Required	Description
thogit_id	string	Yes	Thogit ULID

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_thogit",
    "arguments": {
      "thogit_id": "01JEXAMPLE0000000000THOGIT"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE0000000000THOGIT\",\n  \"name\": \"Implement user authentication\",\n  \"description\": \"Add login/logout with session cookies and OAuth support\",\n  \"tags\": [...],\n  \"created_at\": \"2025-01-15T10:00:00Z\",\n  \"updated_at\": \"2025-01-15T10:00:00Z\"\n}"
      }
    ]
  }
}

---

edit_thogit

Update a thogit’s name and/or description.

Parameters

Name	Type	Required	Description
thogit_id	string	Yes	Thogit ULID
name	string	No	New name
description	string	No	New description

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "edit_thogit",
    "arguments": {
      "thogit_id": "01JEXAMPLE0000000000THOGIT",
      "name": "Implement user auth (OAuth + sessions)"
    }
  }
}

// Response — returns updated thogit
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE0000000000THOGIT\",\n  \"name\": \"Implement user auth (OAuth + sessions)\",\n  ...\n}"
      }
    ]
  }
}

---

delete_thogit

Soft-delete a thogit. It can be restored later with restore_thogit.

Parameters

Name	Type	Required	Description
thogit_id	string	Yes	Thogit ULID

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "delete_thogit",
    "arguments": {
      "thogit_id": "01JEXAMPLE0000000000THOGIT"
    }
  }
}

// Response — returns the deleted thogit
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"id\": \"01JEXAMPLE0000000000THOGIT\",\n  \"name\": \"Implement user auth (OAuth + sessions)\",\n  ...\n}"
      }
    ]
  }
}

---

get_thogits

Search thogits with an optional filter. Pass no filter (or null) to get all thogits.

Parameters

Name	Type	Required	Description
filter	ThogitFilter	No	Filter object, or null/omitted for all thogits

Filter DSL

The filter supports a flat key-value format with dot notation for field access.

Basic Filters

Filter	Example
Full-text search	{"search": "authentication"}
Has tag (by name or ID)	{"has_tag": "Task"}
Direct equality	{"Task.priority": 8}
Null check	{"Task.due": null}

Operators

Use an operator object for comparisons:

Operator	Description	Example
eq / equals	Equal	{"Task.priority": {"eq": 5}}
neq	Not equal	{"Task.priority": {"neq": 0}}
gt	Greater than	{"Task.priority": {"gt": 6}}
gte	Greater than or equal	{"Task.priority": {"gte": 6}}
lt	Less than	{"Task.priority": {"lt": 3}}
lte	Less than or equal	{"Task.priority": {"lte": 3}}
contains	String contains	{"Task.title": {"contains": "auth"}}
starts_with	String starts with	{"Task.title": {"starts_with": "Impl"}}
in	Value in set	{"Task.priority": {"in": [1, 2, 3]}}
exists	Field exists (not null)	{"Task.due": {"exists": true}}
is_null	Field is null	{"Task.due": {"is_null": true}}

Select / MultiSelect Operators

Operator	Description	Example
match	Match variant name	{"Task.status": {"match": "done"}}
match + where	Match variant with data filter	{"Task.status": {"match": "blocked", "where": {"contains": "review"}}}
select_gt	Variant ordering (greater than)	{"Task.status": {"select_gt": "todo"}}
select_gte	Variant ordering (>=)	{"Task.status": {"select_gte": "in_progress"}}
select_lt	Variant ordering (less than)	{"Task.status": {"select_lt": "done"}}
select_lte	Variant ordering (<=)	{"Task.status": {"select_lte": "in_progress"}}

Reference Traversal

Use -> to traverse Reference fields and filter on the referenced thogit:

// Filter by a field on the referenced thogit's tag
{"Task.assignee->Person.name": {"contains": "Alice"}}

// Filter by the referenced thogit's name
{"Task.assignee->name": {"contains": "Alice"}}

Logical Combinators

Combinator	Example
AND	{"and": [{"has_tag": "Task"}, {"Task.priority": {"gt": 5}}]}
OR	{"or": [{"Task.status": {"match": "todo"}}, {"Task.status": {"match": "in_progress"}}]}
NOT	{"not": {"Task.status": {"match": "done"}}}

Comprehensive Search Example

// Request — find high-priority open tasks due before March 2025
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_thogits",
    "arguments": {
      "filter": {
        "and": [
          { "has_tag": "Task" },
          { "Task.priority": { "gte": 7 } },
          { "not": { "Task.status": { "match": "done" } } },
          { "Task.due": { "lt": "2025-03-01" } }
        ]
      }
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\n    \"id\": \"01JEXAMPLE0000000000THOGIT\",\n    \"name\": \"Implement user authentication\",\n    \"tags\": [\n      {\n        \"tag\": { \"name\": \"Task\", ... },\n        \"field_values\": { \"status\": { \"variant\": \"todo\" }, \"priority\": 8, \"due\": \"2025-02-01\" }\n      }\n    ]\n  }\n]"
      }
    ]
  }
}