Skip to main content
Glama
Sign In
MarkIndex

MarkIndex

by jackjin1997
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

search_documents

Read-only

Finds exact terms or identifiers across Markdown sections using keyword search with substring fallback. Scope results by folder or document, then read matching nodes for citable answers.

Instructions

Keyword (BM25) search over section titles, summaries and text, with a substring fallback; handles mixed Chinese/English text and identifiers such as "C++" or "ISO-27001". Returns matching nodes (doc_path, node_id, title_path, line range, snippet). Escalation path: use it when browsing folders and reading structures has not located the answer, or to find an exact term; scope it with folder or doc_path. Then read the hits with get_node_content().

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": "search_documents"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of matching nodes to return (1-50, default 10).
queryYesKeywords to look for: distinctive terms, names or identifiers as they appear in the text (e.g. "ISO-27001 audit", "离职 补偿"). Not a natural-language question.
folderNoRestrict the search to documents under this folder. Library-relative folder path, copied verbatim from a `folders` entry of a browse_documents() response ("" = library root). Never construct one.
doc_pathNoRestrict the search to this document (takes precedence over `folder`). Copy it verbatim from a browse_documents() or search_documents() result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing the ranking method, the substring fallback behavior, multilingual/identifier handling, and the returned fields (doc_path, node_id, title_path, line range, snippet). It does not discuss result ordering confidence or performance/limits beyond the schema's cap, but the behavioral picture is substantially richer than the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the tool does, then when to escalate, then how to scope and follow up. No filler, and each clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating the return fields, and it covers scoping, escalation and the next step in the workflow. For a four-parameter read-only search tool, an agent has everything needed to invoke it correctly.

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% and each parameter already carries a detailed description, including precedence of doc_path over folder and the 'never construct one' rule. The description's 'scope it with `folder` or `doc_path`' largely restates that, so it adds only orientation rather than new semantics.

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 retrieval mechanism (keyword BM25 over section titles, summaries and text) plus a substring fallback, and names the exact text classes it handles (mixed Chinese/English, identifiers like "C++" or "ISO-27001"). This clearly separates it from browsing siblings such as browse_documents and get_document_structure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit escalation rule: use it after browsing folders and reading structures has failed, or to find an exact term. It also names scoping options (folder, doc_path) and the required follow-up action (read hits with get_node_content()), leaving nothing to inference.

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

Deploy Server

Other Tools