Tools

An agent chooses these tools from the user's natural-language request. The MCP client then sends the tool arguments as JSON.

The examples below show only the arguments sent to each tool.

Typical workflow

For a new collection, an agent should normally:

1. Call ping to check the connection.
2. Call list_stores to inspect existing stores.
3. Call create_store if the required store does not exist.
4. Create indexes for metadata fields that will be filtered.
5. Add data with store_entries.
6. Query with similarity_search or get_by_metadata.

Destructive tools should only be called when the user clearly requests the change.

Service information

ping

Checks whether the configured Ahnlich service is reachable.

JSON

{}

Returns the active profile, endpoint, and connection status. When the service is unavailable, the response suggests which service to start.

server_info

Returns information about the configured Ahnlich service.

JSON

{}

The response includes the service version, address, memory information, active profile, and selected AI model where applicable.

Store management

create_store

Creates an empty store.

The AI profile creates a text store using the configured model:

JSON

{
  "store_name": "documents",
  "predicate_keys": ["category", "language"]
}

The DB profile also requires the embedding dimension:

JSON

{
  "store_name": "documents",
  "dimension": 384,
  "predicate_keys": ["category", "language"]
}

Optional error_if_exists defaults to true.

The response confirms the store name and created predicate indexes. DB responses also include the dimension.

list_stores

Lists existing stores.

JSON

{
  "limit": 20
}

limit defaults to 50 and accepts values from 1 to 1024.

The response includes the stores and a truncated value indicating whether additional stores were omitted.

drop_store

Deletes a store and every entry inside it.

JSON

{
  "store_name": "temporary_documents",
  "error_if_not_exists": true
}

error_if_not_exists defaults to true.

This tool is destructive and should only be used when the user explicitly requests permanent removal.

Storing and searching data

store_entries

Adds entries to a store. Existing entries with the same identity may be updated.

The AI profile accepts text:

JSON

{
  "store_name": "documents",
  "entries": [
    {
      "content": "Ahnlich is an in-memory vector database.",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ],
  "preprocessing": "none"
}

preprocessing can be:

• none — send the complete text to the model;
• truncate — allow Ahnlich AI to truncate input to the model limit.

The DB profile accepts precomputed embeddings:

JSON

{
  "store_name": "documents",
  "entries": [
    {
      "embedding": [0.12, 0.42, 0.91],
      "metadata": {
        "category": "documentation"
      }
    }
  ]
}

Every DB embedding must match the store dimension.

The response reports how many entries were inserted and updated.

similarity_search

Finds entries that are closest to a query.

The AI profile accepts natural language:

JSON

{
  "store_name": "documents",
  "query": "How does Ahnlich store vectors?",
  "top_k": 5,
  "algorithm": "cosine",
  "metadata_filter": {
    "language": "en"
  }
}

The DB profile accepts a query embedding:

JSON

{
  "store_name": "documents",
  "query_embedding": [0.11, 0.40, 0.89],
  "top_k": 5,
  "algorithm": "cosine",
  "include_embeddings": false
}

Supported algorithms are:

• cosine
• euclidean
• dot_product

top_k defaults to 5 and accepts values up to 1024.

The response contains the closest entries, their metadata, and similarity values. DB embeddings are omitted unless include_embeddings is true.

get_by_metadata

Retrieves entries matching exact metadata values.

JSON

{
  "store_name": "documents",
  "metadata_filter": {
    "category": "documentation",
    "language": "en"
  },
  "limit": 20
}

All metadata fields in the filter must have predicate indexes. When several fields are provided, every field must match.

limit defaults to 50 and accepts values from 1 to 1024.

The response includes matching entries and a truncated value.

For the DB profile, add "include_embeddings": true when the stored vectors are needed.

delete_by_metadata

Deletes every entry matching exact metadata values.

JSON

{
  "store_name": "documents",
  "metadata_filter": {
    "category": "temporary"
  }
}

All fields in the filter must have predicate indexes.

The response reports the number of deleted entries. This tool is destructive and should only be used when the user explicitly requests deletion.

Metadata indexes

create_predicate_index

Creates indexes for metadata fields.

JSON

{
  "store_name": "documents",
  "keys": ["category", "language"]
}

Use this before filtering with similarity_search, get_by_metadata, or delete_by_metadata.

The response reports how many indexes were created.

drop_predicate_index

Removes indexes from metadata fields without deleting stored entries.

JSON

{
  "store_name": "documents",
  "keys": ["language"]
}

Filters using these fields will stop working until their indexes are recreated.

The response reports how many indexes were removed.

Handling errors

Tool errors include a short explanation and, where possible, a suggested next action.

An agent should follow these recovery steps:

• start the required Ahnlich service when the connection fails;
• call create_store when the requested store does not exist;
• call create_predicate_index when a metadata field is not indexed;

Read-only mode

When AHNLICH_MCP_READ_ONLY=1, only these tools are available:

• ping
• server_info
• list_stores
• similarity_search
• get_by_metadata