Skip to main content
Glama

Search tasks

taskhold_search
Read-only

Search tasks and steps by text in the title or description (case-insensitive, up to 100 tasks scanned). Returns matching lines grouped by status, with ids (a step names the task it belongs to), or a line saying nothing matched.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "taskhold_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesSearch text
statusNoFilter by status
projectNoProject name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing.
project_idNoFilter by project id (project, a name, is easier)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / project / description
      Previous value: -"Project name, e.g. the repo folder (\"api-server\"). Matched case-insensitively (or a project id). An unknown name matches nothing."New value: +"Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
  2. Changed1 schema field changed
    • removedInput schema / properties / project_id / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  3. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower; the description still adds real behavior the annotations lack: matching is case-insensitive, the search covers only title/description, and it scans at most 100 tasks. It also discloses the return shape (lines grouped by status, ids attached, steps naming their parent task, or an explicit 'nothing matched' line), which is valuable for a tool with no output schema. It does not say whether hitting the 100-task limit is signaled to the caller.

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 sentence that front-loads what is searched, then what is scanned, then what comes back. Nothing is wasted, though the return-format clause is packed tightly and could be split for easier scanning.

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 four-parameter read tool with no output schema, the description covers the search semantics, the scan limit, and the return format, so an agent can call it correctly and interpret results. The one gap is that truncation at 100 tasks is stated as a fact rather than explained as a completeness risk to the caller.

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 query, status, project and project_id, including the enum and the 'unknown names match nothing' note in project. The description contributes only that the query searches title or description and is case-insensitive, which is a modest addition. Baseline 3 applies when the schema carries the parameter burden.

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 opens with a specific verb and resource ('Search tasks and steps') and narrows the surface to title/description text, which clearly separates it from the sibling list/get tools. It stops short of naming a specific alternative (e.g. taskhold_list) so an agent can't fully distinguish behavior by name alone, but the purpose is unambiguous.

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 use this when you want text matching, and the mention of case-insensitivity and the 100-task scan cap hints at a lightweight lookup. There is no explicit 'use this instead of taskhold_list when...' guidance, no note on when the scan cap makes results unreliable, and no mention of required preconditions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources