Skip to main content
Glama

find_similar_text

Read-only

Find archived scenes matching a plain-language query over their imagery.

Text-to-scene search: embeds ``query`` ("ships at a berth", "a flooded field")
and ranks the stored *image* vectors by cosine similarity. It only works when
the index was built and this query is embedded with the **same** joint
CLIP-family model whose text and image encoders share a vector space (a
dimension mismatch is reported as an error; ``model`` selects it).

Requires the same prebuilt ``catalog.embed.db`` (``umbra embed build``) and
embedding key as ``find_similar``; the only model call is turning the text
query into a vector. Returns the ranked matches as compact records (each with
the acquisition's ``href`` for ``get_item`` / ``quicklook``) plus attribution.

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

Input Schema

NameRequiredDescriptionDefault
modelNoJoint text-and-image model id. Must match the scene index. A dimension mismatch is an error.
queryYesPlain-language description of the imagery to find, embedded in the same space as the scene index.
top_kNoMaximum matches to return. Default 10.
min_scoreNoMinimum cosine similarity. Default 0. Matches below it are dropped.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / min_score / description
      Added value: +"Minimum cosine similarity. Default 0. Matches below it are dropped."
    • addedInput schema / properties / model / description
      Added value: +"Joint text-and-image model id. Must match the scene index. A dimension mismatch is an error."
    • addedInput schema / properties / query / description
      Added value: +"Plain-language description of the imagery to find, embedded in the same space as the scene index."
    • addedInput schema / properties / top_k / description
      Added value: +"Maximum matches to return. Default 10."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation it discloses real operational traits: the prebuilt catalog.embed.db and embedding-key requirement, the same-model constraint, and that a dimension mismatch surfaces as an error. It also describes the return shape (compact ranked records with each acquisition's `href` for get_item/quicklook, plus attribution), which is the kind of context an agent needs before calling.

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?

Front-loaded with the purpose and organized into purpose, mechanism, prerequisites, and return shape, with no filler sentences. It is somewhat dense with backticked identifiers and markup, which adds visual noise, but each sentence carries 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?

For a read-only search tool with full schema coverage and an output schema, the description covers everything an agent needs: what it does, the prerequisite index/key, the model-matching failure mode, and how results chain into get_item/quicklook. Nothing material is left to inference.

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 baseline is 3, but the description adds genuine meaning: `query` is embedded into the same vector space as the image index, and `model` selects the joint text-and-image encoder that must match the index or fail on dimension mismatch. `top_k` and `min_score` are left to their schema descriptions.

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 (find archived scenes) and immediately narrows it to text-to-scene search by embedding a plain-language query and ranking *image* vectors. It explicitly positions itself against the sibling `find_similar` (same db/key, but the model call here is only the text encoding), so an agent can distinguish the two 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 Guidelines4/5

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

Gives concrete prerequisites: the index must have been built (`umbra embed build`), the embedding key must match, and the query must be embedded with the same joint CLIP-family model as the index. It implies the text-query use case clearly but stops short of an explicit 'use find_similar instead when you have an image' exclusion, so the alternative is only partially spelled out.

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.