Skip to main content
Glama

Lochless

by io.lochless
OverviewDiscussionsAdmin

Search documents

search_documents
Read-only

Search your own documents (your knowledge base) and get every match, not just the top few: a quote from each matching document, with its document id, connection id and date. Returns results, total_results (across all pages), tokens_scanned and next_cursor: pass it back as cursor, with the same query, for the next page. Next pages are free. Narrow with from/to (the document's timestamp) and metadata (exact match; a list = any of). dry_run=true returns documents_matched, tokens_to_scan and the price without searching, for free. read_limit_usd caps what one call may spend: over it, the best-matching documents are read first, and coverage says how many were read of all that match. When coverage.complete is false, pass continue_cursor back to read the next ones. A lookup (one fact or answer) reads only the best-matching results, quicker and cheaper; coverage.mode says fast. Set mode=complete to read every match, or mode=fast for a lookup.

Input Schema

NameRequiredDescriptionDefault
toNoOnly documents whose timestamp is before this: an ISO 8601 date-time, or a YYYY-MM-DD date (through its end, UTC).
fromNoOnly documents whose timestamp is at or after this: an ISO 8601 date-time, or a YYYY-MM-DD date (from its start, UTC).
modeNofast = read only the best-matching results (a lookup: quicker and cheaper, may miss matches). complete = read every matching document, up to read_limit_usd (lists, counts, "every" questions). Default: chosen from the question.
limitNoResults per page, default 50, up to 100.
queryYesWhat to find, in plain language.
cursorNonext_cursor from the previous page of this same call, to get the next page.
dry_runNotrue = return how many documents match and how many tokens this call would scan, and its price, without searching. Free; reads no text.
metadataNoExact metadata matches, e.g. {"client": "acme"}. A list matches any of its values.
read_limit_usdNoThe most this one call may spend from your balance, in US dollars. Over it, the best-matching documents are read first.
continue_cursorNoFrom a response whose coverage is not complete: reads the next best-matching documents, up to read_limit_usd again.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / from / anyOf
      Previous value: -[
-  {
-    "format": "date-time",
-    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-    "type": "string"
-  },
-  {
-    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-    "type": "string"
-  }
-]New value: +[
+  {
+    "format": "date-time",
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  },
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  }
+]
    • changedInput schema / properties / to / anyOf
      Previous value: -[
-  {
-    "format": "date-time",
-    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-    "type": "string"
-  },
-  {
-    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-    "type": "string"
-  }
-]New value: +[
+  {
+    "format": "date-time",
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  },
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  }
+]
  2. Changed1 schema field changed
    • addedInput schema / properties / mode
      Added value: +{
+  "description": "fast = read only the best-matching results (a lookup: quicker and cheaper, may miss matches). complete = read every matching document, up to read_limit_usd (lists, counts, \"every\" questions). Default: chosen from the question.",
+  "enum": [
+    "fast",
+    "complete"
+  ],
+  "type": "string"
+}
  3. Changed20 schema fields changed
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / connection_id
      Removed value: -{
-  "description": "Required for read; use the source's exact connection.",
-  "maxLength": 128,
-  "type": "string"
-}
    • removedInput schema / properties / content_offset
      Removed value: -{
-  "maximum": 9007199254740991,
-  "minimum": 0,
-  "type": "integer"
-}
    • addedInput schema / properties / cursor / description
      Added value: +"next_cursor from the previous page of this same call, to get the next page."
    • addedInput schema / properties / cursor / minLength
      Added value: +1
    • removedInput schema / properties / document_id
      Removed value: -{
-  "description": "Required for read.",
-  "maxLength": 2048,
-  "type": "string"
-}
    • changedInput schema / properties / dry_run / description
      Previous value: -"true = return how many documents match and the tokens and price this query would scan. Free; reads no text."New value: +"true = return how many documents match and how many tokens this call would scan, and its price, without searching. Free; reads no text."
    • removedInput schema / properties / operation
      Removed value: -{
-  "default": "search",
-  "enum": [
-    "search",
-    "browse",
-    "read"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / order
      Removed value: -{
-  "enum": [
-    "asc",
-    "desc"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / page_offset
      Removed value: -{
-  "maximum": 9007199254740991,
-  "minimum": 0,
-  "type": "integer"
-}
    • removedInput schema / properties / participant
      Removed value: -{
-  "maxLength": 320,
-  "type": "string"
-}
    • changedInput schema / properties / query / description
      Previous value: -"Required for search."New value: +"What to find, in plain language."
    • changedInput schema / properties / read_limit_usd / description
      Previous value: -"The most this call may cost, in US dollars. Default 1. Over it, the best-matching documents are read first."New value: +"The most this one call may spend from your balance, in US dollars. Over it, the best-matching documents are read first."
    • removedInput schema / properties / scan_after
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "at": {
-      "format": "date-time",
-      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-      "type": "string"
-    },
-    "id": {
-      "maxLength": 2048,
-      "minLength": 1,
-      "type": "string"
-    }
-  },
-  "required": [
-    "at",
-    "id"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / since
      Removed value: -{
-  "format": "date-time",
-  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-  "type": "string"
-}
    • removedInput schema / properties / source_version
      Removed value: -{
-  "maxLength": 128,
-  "type": "string"
-}
    • removedInput schema / properties / sources
      Removed value: -{
-  "anyOf": [
-    {
-      "items": {
-        "maxLength": 128,
-        "minLength": 1,
-        "type": "string"
-      },
-      "maxItems": 20,
-      "type": "array"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Optional sources for this subquery, within the user's task boundaries."
-}
    • removedInput schema / properties / time_field
      Removed value: -{
-  "enum": [
-    "activity_at",
-    "event_start",
-    "source_updated_at",
-    "indexed_at"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / until
      Removed value: -{
-  "format": "date-time",
-  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
-  "type": "string"
-}
    • addedInput schema / required
      Added value: +[
+  "query"
+]
  4. Added

TDQS

A4.5/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, non-destructive), and the description adds substantial behavioral context beyond them: next pages are free, dry_run reads no text, read_limit_usd triggers priority reading with coverage reporting, and coverage.complete=false requires continue_cursor. This billing and pagination disclosure is exactly the context an agent needs.

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?

Front-loaded with the core purpose and return shape, then layers on pagination, cost, and mode details in a logical order. It is dense and slightly sprawling, with the mode fast/complete idea revisited at several points, but most sentences carry distinct, useful information.

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 10-parameter tool with no output schema, the description covers the important return fields (results, total_results, tokens_scanned, next_cursor, coverage) and cost mechanics thoroughly. It stops short of stating what falls outside its knowledge-base scope or how it relates to sibling tools, but is otherwise nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds interaction semantics the schema cannot express, such as how read_limit_usd and coverage jointly determine continued reads and how cursor must be paired with the same query. This meaningfully extends parameter understanding beyond the structured descriptions.

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 ('Search your own documents (your knowledge base)') and explicitly distinguishes its scope from a top-few/ranking tool by promising 'every match, not just the top few.' An agent can tell what it returns (quote + document id, connection id, date) without opening 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?

Provides clear in-tool guidance: dry_run for cost-free estimation, read_limit_usd to cap spend, continue_cursor when coverage is incomplete, and mode=fast for a quick lookup vs mode=complete for every match. It does not explicitly name when to prefer a sibling like ask_documents or browse_documents, leaving cross-tool routing to inference.

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

All Lochless toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources