Skip to main content
Glama

Search mechanisms

search_mechanisms
Read-onlyIdempotent

Search the registry by name, identifier or a word in the definition, scope, boundary or test. Returns matching entries with id, name, layer, kind, review state, name_test and the first sentence of the definition. A term matches the start of a word, terms shorter than 2 characters are ignored and listed in the note. An entry matching every term ranks first; if none does, the closest partial matches are returned and the note says how many terms they match. Each result states its review state. Entries describe processes in general, not the present state of any country, market or asset.

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

Input Schema

NameRequiredDescriptionDefault
layerNoLayer: core, social, extension, corpus or crisis_type.
limitNoMaximum entries returned (default 20).
queryYesName, identifier or words from the definition. Not empty.
reviewNoReview state filter (versions 1.3.0 and later): all (default), accepted or in_review. The default covers every published entry and each result states its review state; entries in review are published and usable. With accepted the response says how many more matching entries are in review.
versionNoRegistry version, for example "1.4.1" (a leading "v" is accepted). Default: the latest published version (1.4.1). Available: 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0, 1.4.1.

Output Schema

NameRequiredDescriptionDefault
noteNo
queryNo
scopeNoScope of the registry: what the entries are and are not.
totalYes
reviewNo
resultsYes
versionYes
returnedYes
attributionNoCC BY 4.0 attribution: how an answer that uses the entries names the source.
in_review_not_shownNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / version / description
      Previous value: -"Registry version, for example \"1.4.0\" (a leading \"v\" is accepted). Default: the latest published version (1.4.0). Available: 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0."New value: +"Registry version, for example \"1.4.1\" (a leading \"v\" is accepted). Default: the latest published version (1.4.1). Available: 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0, 1.4.1."
  2. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds substantial behavior of its own: prefix matching, a two-character floor for terms, a note listing ignored terms, ranking of all-term matches first, and a partial-match fallback that reports how many terms matched. It also discloses that each result carries its review state and what fields are returned. This is rich operational disclosure beyond what the structured fields supply.

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 front-loaded with purpose, then matching rules, then ranking and fallback, then the domain caveat, and no sentence is filler. It is dense but each clause carries a distinct rule an agent would otherwise have to discover by trial. Slightly more length than strictly necessary given the output schema already lists return fields.

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 full schema coverage, an output schema and strong annotations, this covers the remaining gaps: matching rules, ranking order, partial-match behavior and the semantic limit of the corpus. Nothing an agent needs in order to query it correctly is missing.

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. The description earns above baseline by explaining matching semantics for the query parameter (prefix matching, terms under two characters ignored and reported in the note) and by clarifying that review state is surfaced per result. It does not add anything on layer, limit or version beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Search the registry") and enumerates exactly which fields are searched: name, identifier, definition, scope, boundary, test. That is far more precise than the title alone. It does not explicitly distinguish itself from siblings such as list_mechanisms or get_mechanism, which keeps it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage is implied by the search semantics (word-prefix matching, ranking, partial-match fallback), so an agent can infer this is the discovery tool. However, the description never states when to reach for this instead of list_mechanisms, resolve_name or get_mechanism, and gives no exclusions. The closing caveat about entries describing processes in general is scope-setting, not when-to-use guidance.

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.