Skip to main content
Glama

search_documents

Read-onlyIdempotent

Busca en el CONTENIDO de todos los documentos del workspace usando full-text search en cascada.

Usar cuando:
- El usuario quiere encontrar un documento que habla sobre cierto tema pero no recuerda el nombre
- "¿dónde está el documento sobre X?", "buscá en mis docs algo relacionado con Y"
- Necesitas saber en qué documentos se menciona una persona, proyecto o concepto

Estrategia de búsqueda (en cascada, de más a menos estricta):
1. FTS con websearch_to_tsquery: mejor para frases naturales y multi-palabra
2. Prefix matching: para palabras parciales o términos técnicos
3. ILIKE fallback: garantiza resultados aunque sea por similitud simple

Retorna: document_id, name (título del documento), snippet (extracto con la coincidencia en contexto).
Para leer el documento completo: usar get_document(document_id).
Para navegar la estructura de documentos: usar get_documents.

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
limitNoMáximo resultados (default: 20)
queryYesTexto a buscar en el contenido de los documentos (mínimo 2 caracteres, soporta frases)
workspace_idNoUUID del workspace, o su nombre tal como lo dice el usuario ('Acme', 'el personal'). Omitir = TODOS los workspaces de la persona, en una sola llamada

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: a three-stage cascade (websearch_to_tsquery → prefix matching → ILIKE fallback) that tells the agent results may be fuzzy rather than exact, plus the return fields. It stops short of describing ranking/ordering of the merged results.

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?

Well front-loaded: purpose first, then when-to-use, then search strategy, then return shape and next steps. Bullets and numbered cascade keep it scannable. Slightly verbose with a redundant example phrasing, but no sentence is filler.

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?

No output schema exists, yet the description names the returned fields (document_id, name, snippet) and explains snippet is the match in context. Combined with the cascade explanation and explicit follow-up tools, an agent has everything needed to call it and act on results.

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 the schema already documents limit defaults, the 2-character minimum, phrase support, and the workspace_id omission behavior. The description reinforces that 'query' matches document content and that omitting workspace_id spans all workspaces, but adds little parameter meaning beyond 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 ('Busca en el CONTENIDO de todos los documentos del workspace') plus the mechanism (full-text search en cascada), which lets an agent distinguish it from get_document (full read) and get_documents (structure navigation) without opening a schema.

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?

Provides an explicit 'Usar cuando' block with concrete user phrasings ('¿dónde está el documento sobre X?') and names the alternatives for adjacent needs: get_document for full text and get_documents for structure. When-to-use and where-to-go-next are both covered.

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