Skip to main content
Glama

ai_search

Idempotent

Run natural-language discovery across concepts, entities, and cached values to find relevant data; use it as the default search entry point before narrower semantic searches.

Instructions

Default search entry point — call this for fuzzy/natural-language discovery. Superset of semantic_search/semantic_search_entities/semantic_search_unified (concepts + entities + cached values); do not call those in parallel with this.

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

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of concepts to return
queryYesNatural language query (e.g., "Asian inflation indicators")
scopeNoOptional named retrieval scope constraining the concepts list; the response names the scope that governed it (see scope_list)
value_dateNoDate for values (e.g., "2024-01-01") - only if include_values=True
entity_typeNoFilter by entity type (country, stock, industry, etc.)
include_valuesNoIf True, fetch actual values from semantic_observations

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is mostly covered. The description's mention of 'cached values' hints at why readOnlyHint is false (value retrieval may populate a cache), but it never explains that cost, latency, or what the cache behavior implies for repeated calls. Useful context, but not rich disclosure beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the routing decision, followed by the superset/anti-parallel constraint. No filler, and the most decision-relevant information comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full schema and an output schema present, the description only needs to carry routing and relationship semantics, which it does, including a pointer to scope_list for scope governance. The only small gap is that it never characterizes the cost or behavior of include_values=True, which changes the nature of the call.

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 description coverage is 100%, so all six parameters including limit, scope, value_date, entity_type, and include_values are already documented in the schema. The description adds no syntax, default, or interaction detail beyond that, which is acceptable but not additive.

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 states a specific verb and resource — a default search entry point for fuzzy/natural-language discovery — and explicitly positions itself as a superset covering concepts, entities, and cached values. An agent can distinguish it from semantic_search, semantic_search_entities, and semantic_search_unified without inspecting their schemas.

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 gives both a positive routing rule ('call this for fuzzy/natural-language discovery' as the default) and a negative one ('do not call those in parallel with this'), naming the three alternatives it subsumes. This is exactly the when-to-use/when-not-to-use guidance needed to avoid redundant parallel calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.