Skip to main content
Glama
thyn-ai

Telys

Official
by thyn-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

telys_search_lexical

Read-onlyIdempotent

Perform exact-term keyword search using BM25 to find identifiers and rare tokens that semantic search may miss. Requires a lexical-enabled collection and pre-built lexical index.

Instructions

On-device BM25 lexical (keyword) search — exact-term matching for identifiers and rare tokens where semantic search is fuzzy. Sibling: use telys_search for embedding-ranked (vector) retrieval; this tool is the BM25 path, no embedding involved. Requires the collection to have been created with lexical=True AND telys_build_lexical to have run, otherwise the call fails. Required: collection, query. Optional: top_k (default 5), where (single-key equality filter), explain (default false; include per-hit score explanations). Fails when the collection does not exist or the lexical index was never built.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYeskeyword query for BM25 matching
top_kNomaximum hits to return, ordered best-first
whereNooptional single-key equality filter, e.g. scope=project:acme (one key only)
explainNoinclude per-hit score explanations
collectionYesname of an existing collection created with lexical=True

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.1.1
    • addedInput schema / properties / collection / description
      Added value: +"name of an existing collection created with lexical=True"
    • addedInput schema / properties / explain / description
      Added value: +"include per-hit score explanations"
    • addedInput schema / properties / query / description
      Added value: +"keyword query for BM25 matching"
    • addedInput schema / properties / top_k / description
      Added value: +"maximum hits to return, ordered best-first"
    • changedInput schema / properties / where / description
      Previous value: -"optional single-key equality filter"New value: +"optional single-key equality filter, e.g. scope=project:acme (one key only)"
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful extra behavioral context: the tool fails if the collection doesn't exist or the lexical index was never built, and explain adds per-hit score explanations. No contradiction with annotations.

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?

The description is dense and front-loaded, leading with the core behavior and sibling distinction. It loses a point for slight redundancy: 'otherwise the call fails' and the final 'Fails when...' sentence restate the same failure concept.

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?

For a five-parameter search tool with no output schema, this description covers the essential guidance: what the tool does, when to use it, required preconditions, all parameters, and explicit failure modes. An agent has enough information to invoke it correctly and avoid common mistakes.

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 the schema already documents all five parameters. The description adds value by tying the collection parameter to the telys_build_lexical prerequisite and clarifying that query is for BM25 exact-term matching, but most parameter details are already in 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?

The description names the exact operation: on-device BM25 lexical keyword search with exact-term matching. It explicitly distinguishes this from the sibling telys_search, which handles vector/embedding retrieval, so an agent can tell them apart without opening either 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?

It explicitly identifies when to use this tool versus the alternative: exact-term matching for identifiers and rare tokens versus fuzzy semantic search. It also states the required precondition that the collection must have lexical=True and telys_build_lexical must have run, plus the failure conditions when those are not met.

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