# search\_documents

Search documents by full text, reading each as it is now and never an earlier version.

read-only · idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Quote phrases and prefix `-` to exclude. Narrow to one agent with [`agent_id`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-agent_id) or one type with [`type`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-type).

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/SearchDocuments \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "<query>"
}'
```

```bash
komrad rpc search-documents \
  --query '<string>'
```

```json
{
  "name": "search_documents",
  "arguments": {
    "query": "<query>"
  }
}
```

Offered by the komrad MCP server to writer, reviewer, orchestrator agents.

## Request

### SearchDocumentsRequest

| Field | Type | Description |
| --- | --- | --- |
| [`query`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-query) | string\* at most 500 characters | The words to search for in each document's newest version, matched whole and stemmed. A quoted phrase matches in order, and a leading minus excludes a word. |
| [`agent_id`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-agent_id) | uuid | The agent whose documents to search, by id. Unset searches every agent's, archived agents included. |
| [`type`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-type) | string not empty at most 100 characters | The type of documents to search, by name. Unset searches every type. |
| [`limit`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsRequest-limit) | int32 between 0 and 200 | How many documents to return across `matches` and `near`. Zero returns up to fifty. |

## Response

### SearchDocumentsResponse

| Field | Type | Description |
| --- | --- | --- |
| [`matches`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsResponse-matches) | [DocumentHit\[\]](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit) | The documents that contain every word, best match first. |
| [`near`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-SearchDocumentsResponse-near) | [DocumentHit\[\]](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit) | The documents that contain a word only inside a longer word, closest first. |

## Types

### DocumentHit

DocumentHit is one document that matched a search.

| Field | Type | Description |
| --- | --- | --- |
| [`document_id`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit-document_id) | uuid\* | The document's id. |
| [`agent_id`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit-agent_id) | uuid\* | The id of the agent that owns the document. |
| [`name`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit-name) | string | The document's title. |
| [`snippet`](https://komrad.dev/latest/api/agent/search-documents.md#komrad-agent-v1-DocumentHit-snippet) | string | The text around the match, with the matched words marked. |
