Skip to main content
Glama

Search tasks and documents, archive included

find
Read-onlyIdempotent

Search open and archived tasks and documents: words in query, the task fields below to sift, source to see if something was filed, doc for lines inside one document. A task matched in its page, steps or notes brings the line.

Instructions

Search open and archived tasks and documents: words in query, the task fields below to sift, source to see if something was filed, doc for lines inside one document. A task matched in its page, steps or notes brings the line. Open a task hit with read, a document hit with read_doc.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoDate or deadline on or before this day
docNoSearch inside this document: lines with every word, their numbers and section
tagNoCarrying this tag, # or not. Any sifting field leaves documents out
fromNoDate or deadline on or after this day (2026-08-31)
listNoIn this list, as `catch_up` names it
afterNoSkip this many tasks, to page on while `total` is higher. Documents are not paged: raise `limit`
limitNoAt most 100, 10 by default
linesNoFalse: titles alone, without their `line`
queryNoWords that must all turn up, in any order, accents or not (with `doc`, on one line); quote a phrase. Not needed when sifting
scopeNoDefaults to either
aroundNoWith `doc`: lines each side of a hit, 0 to 10, 1 by default
folderNoOnly documents in this folder or below, by name, path or id
sourceNoWhether this exact source was filed already; not with `query`
part_ofNoOnly the parts of this task, by id
by_agentNoTrue: filed by an agent; false: by the person
said_doneNoTrue: an agent said done or not doing and the person has not decided; false: nobody did
from_sourceNoTasks whose `source` starts with this, however written: «sereno» brings all read from there

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.47.1
    • changedInput schema / properties / after / description
      Previous value: -"Skip this many tasks, to page on while `total` is higher. Documents are not paged: `docsTotal` counts them"New value: +"Skip this many tasks, to page on while `total` is higher. Documents are not paged: raise `limit`"
    • changedInput schema / properties / doc / description
      Previous value: -"Search inside this document: lines with every word, their numbers, neighbours cut at 200 characters, and section"New value: +"Search inside this document: lines with every word, their numbers and section"
    • changedInput schema / properties / limit / description
      Previous value: -"At most 100, 20 by default"New value: +"At most 100, 10 by default"
    • addedInput schema / properties / lines
      Added value: +{
      +  "description": "False: titles alone, without their `line`",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / scope / description
      Previous value: -"Defaults to either: open and archived together"New value: +"Defaults to either"
  2. Changed2 schema fields changedv1.47.0
    • changedInput schema / properties / list / description
      Previous value: -"In this list, as `lists` names it"New value: +"In this list, as `catch_up` names it"
    • removedInput schema / properties / open_to_agents
      Removed value: -{
      -  "description": "True: the person's tasks opened to agents; false: kept to themselves",
      -  "type": "boolean"
      -}
  3. Changed16 schema fields changedv1.43.2
    • changedInput schema / properties / after / description
      Previous value: -"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"New value: +"Skip this many tasks, to page on while `total` is higher. Documents are not paged: `docsTotal` counts them"
    • changedInput schema / properties / around / description
      Previous value: -"With `doc`: how many lines to bring on each side of a hit, 1 by default, 0 for none, at most 10"New value: +"With `doc`: lines each side of a hit, 0 to 10, 1 by default"
    • changedInput schema / properties / by_agent / description
      Previous value: -"True for what an agent filed, false for what the person wrote"New value: +"True: filed by an agent; false: by the person"
    • changedInput schema / properties / doc / description
      Previous value: -"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"New value: +"Search inside this document: lines with every word, their numbers, neighbours cut at 200 characters, and section"
    • changedInput schema / properties / folder / description
      Previous value: -"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"New value: +"Only documents in this folder or below, by name, path or id"
    • changedInput schema / properties / from / description
      Previous value: -"Its date or deadline on this day or after (2026-08-31)"New value: +"Date or deadline on or after this day (2026-08-31)"
    • changedInput schema / properties / from_source / description
      Previous value: -"Only tasks whose `source` starts with this, however it is written: «sereno», «sereno#» and «sereno: » all bring everything read out of that one place"New value: +"Tasks whose `source` starts with this, however written: «sereno» brings all read from there"
    • changedInput schema / properties / list / description
      Previous value: -"In this list, named as `lists` names it"New value: +"In this list, as `lists` names it"
    • changedInput schema / properties / open_to_agents / description
      Previous value: -"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"New value: +"True: the person's tasks opened to agents; false: kept to themselves"
    • changedInput schema / properties / part_of / description
      Previous value: -"Only the parts of this task, by its id"New value: +"Only the parts of this task, by id"
    • changedInput schema / properties / query / description
      Previous value: -"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"New value: +"Words that must all turn up, in any order, accents or not (with `doc`, on one line); quote a phrase. Not needed when sifting"
    • changedInput schema / properties / said_done / description
      Previous value: -"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"New value: +"True: an agent said done or not doing and the person has not decided; false: nobody did"
    • changedInput schema / properties / scope / description
      Previous value: -"Defaults to either: the open tasks and the archive together, which is where how something was solved before is found"New value: +"Defaults to either: open and archived together"
    • changedInput schema / properties / source / description
      Previous value: -"Ask whether this exact source was proposed already"New value: +"Whether this exact source was filed already; not with `query`"
    • changedInput schema / properties / tag / description
      Previous value: -"Carrying this tag, with or without the #. Any sifting field leaves the documents out of the answer"New value: +"Carrying this tag, # or not. Any sifting field leaves documents out"
    • changedInput schema / properties / to / description
      Previous value: -"Its date or deadline on this day or before"New value: +"Date or deadline on or before this day"
  4. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, closed-world, non-destructive behavior, so the description only needs to add context. It does: search spans archive by default, a task matched in page/steps/notes returns the `line`, and documents are not paged. It does not disclose rate limits or result ordering, but nothing is missing that would cause a misuse.

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 compact sentences with the primary search modes front-loaded and no filler. The telegraphic style ("the task fields below to sift", "to see if something was filed") is efficient but occasionally cryptic and costs a little immediate comprehension.

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 tool with no output schema, the description covers the main entry paths and the follow-up calls, which is the information an agent most needs. The gap is return shape: `total`, paging via `after`, and hit structure are only implied (via `line`) rather than described.

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 baseline is 3 and most of the parameter meaning already lives in the schema. The description adds a few genuine cross-parameter facts the schema does not state — `source` conflicts with `query`, sifting fields drop documents — but leaves the other 14 parameters to 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 set: "Search open and archived tasks and documents", and immediately narrows the two result families (task hits vs. document/line hits). An agent can tell this apart from `docs` (listing) and `read`/`read_doc` (opening a hit) without consulting 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?

Gives concrete routing guidance for the main modes: use `doc` for lines inside one document, `source` to check whether something was filed, and open task hits with `read` and document hits with `read_doc`. It also warns that any sifting field excludes documents. It stops short of explicitly saying when to prefer this over `docs` or `catch_up`, so no exclusions are stated.

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