Skip to content

Utility Tools

Utility tools help you debug filters, understand query resolution, and render rich content inline.

validate_filter

Validate a filter without executing it. Returns whether the filter is valid, resolved tag information, and any warnings about missing fields or invalid traversals.

Parameters

Name	Type	Required	Description
`filter`	object	Yes	The filter JSON to validate
`target`	string	Yes	What the filter targets: `"thogits"` or `"tags"`

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_filter",
    "arguments": {
      "filter": {
        "and": [
          { "has_tag": "Task" },
          { "Task.priority": { "gte": 5 } },
          { "Task.status": { "match": "done" } }
        ]
      },
      "target": "thogits"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"valid\": true,\n  \"resolved_tags\": {\n    \"Task\": {\n      \"id\": \"01JEXAMPLE00000000000TAGID\",\n      \"fields\": { \"priority\": \"Number\", \"status\": { \"type\": \"Select\", ... } }\n    }\n  },\n  \"warnings\": []\n}"
      }
    ]
  }
}

// Request — references a non-existent tag
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "validate_filter",
    "arguments": {
      "filter": {
        "NonExistentTag.field": { "eq": "value" }
      },
      "target": "thogits"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"valid\": false,\n  \"errors\": [\n    { \"message\": \"Tag not found: NonExistentTag\" }\n  ]\n}"
      }
    ]
  }
}

// Request — validate a tag filter
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "validate_filter",
    "arguments": {
      "filter": { "search": "task" },
      "target": "tags"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"valid\": true\n}"
      }
    ]
  }
}

explain_query

Get a detailed explanation of how a filter is resolved, including which tags and fields are referenced, their types, and any warnings about potential issues.

Parameters

Name	Type	Required	Description
`filter`	object	Yes	The filter JSON to explain

Example

// Request — explain a complex filter
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "explain_query",
    "arguments": {
      "filter": {
        "and": [
          { "has_tag": "Task" },
          { "Task.priority": { "gte": 7 } },
          { "Task.assignee->Person.name": { "contains": "Alice" } },
          { "not": { "Task.status": { "match": "done" } } }
        ]
      }
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"explanation\": \"Filter requires tag 'Task' (01JEXAMPLE00000000000TAGID).\\nField 'priority' (Number) >= 7.\\nField 'assignee' (Reference) traverses to tag 'Person' (01JEXAMPLE0000000000PERSID), field 'name' (String) contains 'Alice'.\\nExcludes status variant 'done'.\",\n  \"resolved_tags\": {\n    \"Task\": {\n      \"id\": \"01JEXAMPLE00000000000TAGID\",\n      \"fields\": { \"priority\": \"Number\", \"status\": { \"type\": \"Select\", ... }, \"assignee\": \"Reference\" }\n    },\n    \"Person\": {\n      \"id\": \"01JEXAMPLE0000000000PERSID\",\n      \"fields\": { \"name\": \"String\" }\n    }\n  },\n  \"warnings\": []\n}"
      }
    ]
  }
}

render_react

Render a React component with Tailwind CSS inline in the chat. This is used by AI assistants to present information in a visually polished way.

Parameters

Name	Type	Required	Description
`code`	string	Yes	JSX/TSX source code with a default-exported React component

Constraints

Must have a default export: export default function Name() { ... }
Import hooks from "react" only when needed: import { useState } from "react";
Use Tailwind classes via className for all styling — no inline styles
Only React and Tailwind are available — no external dependencies
The component renders inline, so keep it compact

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "render_react",
    "arguments": {
      "code": "export default function TaskSummary() {\n  return (\n    <div className=\"p-3 bg-gray-50 border border-gray-200 rounded-lg text-sm text-gray-700\">\n      <div className=\"font-medium text-gray-900 mb-1\">Sprint Overview</div>\n      <div className=\"flex gap-4\">\n        <span>Done: 8</span>\n        <span>In Progress: 3</span>\n        <span>Todo: 5</span>\n      </div>\n    </div>\n  );\n}"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"render_id\": \"01JEXAMPLE00000000RENDERID\",\n  \"js\": \"/* compiled JavaScript */\",\n  \"css\": \"/* extracted Tailwind CSS */\"\n}"
      }
    ]
  }
}