ColdState Knowledge Search MCP Server
https://github.com/daniel-coldstate/coldstate-mcp
Semantic search over 64.6M knowledge entries — the structured alternative to web search APIs and web scraping for LLM agents. No crawling, no rate limits, sub-3s responses. Cloud-hosted at services.coldstate.ai
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.2/5 across 16 of 16 tools scored. Lowest: 3.4/5.
Most tools have clearly distinct purposes, but the three search tools (search, search_global, batch_search) and the two relation tools (related, isomorph) could cause initial confusion despite clear descriptions. Overall boundaries are clear enough that agents should select correctly with careful reading.
Every tool uses the consistent coldstate_ prefix followed by a descriptive verb_noun pattern (e.g., batch_search, browse_documents, list_indexes). The naming is uniform and predictable, making the toolset easy to navigate.
At 16 tools, the server sits at the upper edge of what feels reasonable, and the calibration guidance flags 16-25 as heavy. However, each tool serves a distinct function in the knowledge-search lifecycle, so the count is defensible but still slightly high for a single server.
The toolset covers the full read-only knowledge workflow: searching, browsing, fetching, citing, verifying, explaining, resolving, and exploring relations. It also includes meta-tools for capabilities, domains, snapshots, and statistics, leaving no obvious gaps for its stated purpose.
coldstate_batch_searchARun several knowledge-base queries in one call against a single consistent kb_snapshot. Returns each query with its ranked results — efficient and snapshot-consistent across the whole batch.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per query | |
| domain | No | Optional domain filter applied to all queries | |
| queries | Yes | 1–10 queries |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description adds meaningful context: it explains the snapshot-consistent behavior across the batch and that results are ranked per query. This is useful behavioral information not present in 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and every clause adds value. It avoids fluff and clearly communicates the batch behavior and return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It adequately describes the return shape ('ranked results per query') and the snapshot-consistency guarantee, which is sufficient given the simple 3-parameter schema and the safety annotations. No output schema exists, so the description covers the essential outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all three parameters (limit, domain, queries). The tool description does not add any parameter-specific semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs multiple knowledge-base queries in one call against a consistent snapshot, and returns ranked results per query. This distinguishes it from single-query siblings like coldstate_search by emphasizing the batch aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use when you want to run several queries efficiently with snapshot consistency. However, it does not explicitly name alternative tools (e.g., coldstate_search) or state when not to use this batch variant, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_browse_documentsBBrowse documents in a ColdState index. Returns titles, snippets, content, state classification, and E-scores.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max documents to return | |
| offset | No | Offset for pagination | |
| index_id | Yes | Index ID, e.g. idx_... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context by enumerating the returned data fields, which is useful, but it does not disclose additional behavioral traits such as pagination behavior, ordering, or any constraints beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that are front-loaded with the core action and immediately followed by the return fields. Every word earns its place, with no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple read-only browsing tool, the description adequately covers what it does and what it returns. The lack of an output schema is mitigated by listing the returned fields. However, it does not mention ordering or any filtering behavior, which could be relevant for a 'browse' operation, and it doesn't reference sibling tools for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage), so the schema already explains the parameters. The description adds no extra semantic meaning beyond the schema, not even reiterating the parameter purposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Browse') and identifies the resource ('documents in a ColdState index'), while also listing the return fields (titles, snippets, content, state classification, E-scores). This makes the purpose clear, though it does not explicitly differentiate from sibling tools like search or fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other coldstate tools (e.g., search, fetch, list_indexes). The description simply states what it does without mentioning scenarios, alternatives, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_capabilitiesAMachine-readable manifest of this server: available tools, knowledge domains, current kb_snapshot, determinism guarantees, and limits. Call this first to self-configure.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations, such as returning current kb_snapshot, determinism guarantees, and limits, and positions the tool as a self-configuration mechanism. It does not detail output format, but the risk profile is low and well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a scannable colon-delimited content list and a direct action instruction. Every word contributes value; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-argument manifest endpoint, the description sufficiently covers purpose, content categories, and invocation order. The phrase 'machine-readable manifest' hints at the return format, and given the tool's simplicity, the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so the baseline of 4 applies. The description correctly omits parameter details because there is nothing to document; no additional semantic burden exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a 'machine-readable manifest of this server' and enumerates its contents (available tools, knowledge domains, kb_snapshot, determinism guarantees, limits). It is immediately distinguishable from operational siblings like search or browse by framing itself as an entry-point/self-configuration resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit timing guidance: 'Call this first to self-configure.' This clearly implies invocation before other tools. It does not name alternatives or exclusions, but the entry-point role is clear enough for a zero-parameter discovery tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_citeAGet a canonical, reproducible citation for a knowledge entry by id (title, domain, source, content_hash, kb_snapshot). Cite a fact so it can be re-verified later with coldstate_verify.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable knowledge entry id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds useful context by stating the citation is 'canonical, reproducible' and listing its fields, aligning with the idempotency hint and revealing what the output will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the core action in the first sentence and the purpose/cross-reference in the second. It is front-loaded, free of filler, and every phrase contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, complete annotations, and no output schema, the description sufficiently covers what the tool does and what the citation includes (title, domain, source, content_hash, kb_snapshot). It could go deeper into return format, but for this simple tool it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'id' parameter with description, minLength, and maxLength. The tool description only repeats that the operation is 'by id' without adding further constraints or formatting details, which matches the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Get a canonical, reproducible citation for a knowledge entry by id.' It also enumerates the citation's components (title, domain, source, content_hash, kb_snapshot), which distinguishes it from sibling tools like coldstate_verify or coldstate_fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence, 'Cite a fact so it can be re-verified later with coldstate_verify,' provides a clear use case and explicitly ties the tool to a sibling for verification. While it doesn't list when not to use it, the context strongly implies the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_domainsAList all available knowledge domains in ColdState's global knowledge base with entry counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the scope 'global knowledge base' and 'entry counts' as useful context, though it doesn't disclose additional behavioral traits like pagination—which is less critical for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, scope, and output characteristic ('entry counts') without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool with rich annotations and no output schema, the description is complete: it tells the agent what the tool lists and that counts are included. The absence of output schema is mitigated by this explicit description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and a schema coverage of 100%, the baseline is 4. The description adds no parameter details because none are needed; it correctly focuses on what the tool returns rather than any parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'all available knowledge domains in ColdState's global knowledge base' with 'entry counts.' This distinguishes it from siblings like coldstate_list_indexes and coldstate_search, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to enumerate knowledge domains and their entry counts. While it doesn't explicitly mention alternatives or when-not-to-use, the purpose is self-evident and sufficiently narrow, making it a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_explainAExplain why a specific document ranked for a query. Returns a per-term relevance breakdown and an overall match summary — deterministic and reproducible.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query to explain against | |
| doc_id | Yes | Document ID, e.g. "doc_42" or "42" | |
| index_id | Yes | Index ID, e.g. idx_... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the deterministic and reproducible nature of the results and outlines the return composition, which goes beyond the structured fields without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, action-first, with no redundant information. Each sentence adds value: the first states the purpose, the second describes the output and a key behavioral trait.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only explain tool, the description adequately covers purpose, output, and determinism. There is no output schema, but the description summarizes the return value. It lacks explicit prerequisites/error behavior, but these are minor given the annotation safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters with descriptions and patterns (e.g., doc_id example, index_id pattern). The description adds no additional parameter-specific details, so it earns the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Explain why a specific document ranked for a query') and specifies the output (per-term relevance breakdown, overall match summary). This distinguishes it from sibling tools like search, fetch, or browse, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (to understand document ranking for a query), but it does not explicitly mention alternatives or exclusions. For instance, it doesn't compare with search or browse, but the intent is obvious enough for an agent to choose it for explainability tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_fetchAFetch a single knowledge-base entry verbatim by its stable id (e.g. "eng_000229f438f7cebd"). Deterministic retrieval — returns the full record plus a content_hash and kb_snapshot for reproducible citation.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable knowledge entry id, e.g. eng_... or soc_... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description adds that retrieval is deterministic and that the response includes a content_hash and kb_snapshot for reproducible citation, giving useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with high information density. Zero waste, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-id fetch with no output schema, the description explains the return contents (full record plus hash/snapshot) and deterministic behavior. Could mention not-found behavior, but that's a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'id' is fully described in the schema with format examples; the description reinforces this with another concrete example but does not add significant new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' with a clear resource 'a single knowledge-base entry', qualifies it with 'verbatim' and 'by its stable id', and provides an id example. This clearly differentiates it from sibling search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving an exact entry when you have a stable id, emphasizing deterministic retrieval for reproducible citation. However, it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_isomorphACross-domain structural analog: given a knowledge entry id, find its closest structural twin in each OTHER domain ("same structure, different domain") via embedding-cluster similarity. Deterministic. Use coldstate_resolve to turn a name into an id first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable knowledge entry id, e.g. eng_... or soc_... | |
| limit | No | Max cross-domain analogs (one per domain) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description need not repeat safety basics. It adds valuable behavior beyond annotations: the algorithm ('embedding-cluster similarity'), determinism, and the specific cross-domain twin concept. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, all information-dense and front-loaded with the core purpose. It includes the algorithm, determinism, and a critical prerequisite without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of output schema, the description sufficiently explains what the tool does, how it works, and how to prepare input. It could mention the return shape more explicitly, but it is already complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'id' and 'limit', so the schema does much of the work. The description adds semantic value by explaining that the id is a 'knowledge entry id' and pointing users to coldstate_resolve for name-to-id resolution, which enriches understanding of the id parameter beyond schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('find its closest structural twin') on a specific resource ('knowledge entry id') and clearly differentiates it from sibling tools by targeting 'each OTHER domain' rather than same-domain search or general lookup. It names the exact purpose and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is for cross-domain structural analogs when you have a knowledge entry id, and it explicitly instructs to use coldstate_resolve first if you have a name. It does not enumerate exclusions versus siblings like coldstate_related, but the 'OTHER domain' distinction and prerequisite instruction provide clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_list_indexesAList all your ColdState indexes with their status, mode, document count, and domain preset.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific output fields (status, mode, document count, domain preset), which is useful context beyond the annotations. However, it does not mention any additional behavioral traits like pagination, sorting, or authentication requirements, so it provides only marginal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the action and resource, and directly lists the output fields. Every word earns its place, with no filler or redundant information. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list operation with no output schema, but the description enumerates the exact fields returned (status, mode, document count, domain preset), providing sufficient detail for the agent to understand what to expect. Given the low complexity and the strong annotations, the description is complete enough for a tool of this kind.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description correctly implies no parameters are needed. Since there are no parameters to describe, the baseline score of 4 applies, and the description does not introduce any confusion about parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all ColdState indexes with specific attributes (status, mode, document count, domain preset). The verb 'List' and resource 'indexes' are unambiguous. However, it does not explicitly differentiate it from sibling tools like coldstate_domains or coldstate_stats, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It simply states what it does without any context about typical use cases or exclusions. For example, it does not say to use this to get an overview before searching, or to avoid it if you need document-level details. No usage guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_resolveAResolve a name, alias, or surface form to its canonical ColdState knowledge entry (id + title). Deterministic: an exact title match wins, else the top relevance-Ψ entry. Returns the canonical entry plus alternatives. Use the returned id with coldstate_fetch / coldstate_related.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max alternative candidates | |
| query | Yes | The name/term/alias to resolve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already declare safe/idempotent read), the description adds deterministic matching behavior (exact title match wins, else top relevance-Ψ) and the output composition (canonical entry plus alternatives). This provides meaningful behavioral context beyond what structured fields convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences) and front-loaded with the core action, followed by deterministic behavior, output summary, and a follow-up tip. Every sentence contributes information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool, complete schema, and safe annotations, the description adequately covers the return value (canonical entry + alternatives), deterministic behavior, and downstream usage. No output schema exists, so the description's explicit mention of id + title and alternatives suffices for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for query and limit. The description minimally reinforces query's semantics but doesn't add details beyond the schema; the limit's effect on alternatives is implied but not explicitly explained in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool resolves a name/alias/surface form to a canonical ColdState entry with id + title, and distinguishes it from siblings by mentioning follow-up tools coldstate_fetch and coldstate_related. It uses a specific verb and resource, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the usage context: when you have a name/alias and need the canonical ID, and it directs to use the returned id with coldstate_fetch/coldstate_related. However, it doesn't explicitly contrast with sibling search tools or mention when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_searchASearch a ColdState index by collection name or index ID. Returns ranked results with Ψ scores and state classification (CRYSTALLINE/FLUID/REACTIVE/DECOHERENT). Provide exactly one of collection or index_id.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return | |
| query | Yes | The search query | |
| offset | No | Offset for pagination | |
| index_id | No | Index ID to search, e.g. idx_... (mutually exclusive with collection) | |
| collection | No | Collection name to search (mutually exclusive with index_id) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and idempotent, so the description does not need to restate that. It adds valuable behavioral context by specifying the output format (ranked results with Ψ scores and state classification) and the mutual exclusivity requirement, which goes beyond the annotations and enriches the agent's understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first covers purpose and output, the second gives a clear directive. Every word earns its place; no redundant filler or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with good schema coverage and safety annotations, the description sufficiently communicates the key behaviors (return format, mutual exclusivity). It does not explain pagination details, but those are in the schema. The absence of an output schema is compensated by mentioning the output fields, making the description complete enough for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description repeats the 'exactly one' constraint but does not add additional meaning beyond the schema's own descriptions (e.g., 'mutually exclusive with collection'). Since the schema already carries the load, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Search a ColdState index'), the target resource (by collection name or index ID), and the return type (ranked results with Ψ scores and state classification). This distinguishes it from siblings like coldstate_search_global and coldstate_batch_search, which imply different scopes or modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear constraint ('Provide exactly one of `collection` or `index_id`') but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The usage context is implied by the tool name and description, but there is no explicit guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_search_globalASearch ColdState's global knowledge base (48.4M+ entries across 35 domains including SCIENCE, MEDICINE, TECHNOLOGY, HISTORY, etc). Returns deterministically ranked results with Ψ relevance scores and a state classification. Optionally filter by domain.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return | |
| query | Yes | The search query | |
| domain | No | Filter by knowledge domain (e.g. MEDICINE, SCIENCE, TECHNOLOGY, HISTORY, LAW, CODE). Case-insensitive. | |
| offset | No | Offset for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond that: deterministic ranking, relevance scores, and state classification. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main verb and resource. It packs significant detail (scale, domains, output behavior, optional filter) into two sentences with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description sufficiently conveys what the tool returns (ranked results with relevance scores and state classification) and covers the main use case. Combined with full schema parameter descriptions and safety-related annotations, the context is complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all four parameters (100% coverage). The description adds minimal extra semantic value by mentioning optional domain filtering, which is already documented. It does not elaborate on limit, offset, or query formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a global search over ColdState's knowledge base, with scope (48.4M+ entries, 35 domains) and unique output characteristics (Ψ relevance scores, state classification). This distinguishes it from sibling tools like coldstate_search, which likely targets a more specific subset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is a global search with optional domain filtering, implying it is for cross-domain queries. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_snapshotAGet the current knowledge-base snapshot/version id. Pin this kb_snapshot for reproducibility: the same query against the same kb_snapshot returns identical results.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and not destructive. The description adds the key behavioral trait that the same query against the same snapshot returns identical results, and clarifies it returns the current version ID. This goes beyond the annotations by specifying the reproducibility contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every word earns its place. It concisely conveys purpose and behavioral guarantee without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple retrieval tool with no parameters and strong annotations, the description fully covers purpose, usage context, and reproducibility. The lack of output schema is acceptable given the simplicity of the tool and the clear description of what it returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. The description mentions kb_snapshot as a concept but not as an input, and since there are no parameters, no additional parameter semantics are needed. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the current knowledge-base snapshot/version ID using the verb 'Get' and a specific resource. It distinguishes from sibling tools that perform searches, fetches, or other operations, and adds the purpose of reproducibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when to use the tool: when a stable snapshot ID is needed for reproducible queries. It explains the behavioral guarantee that the same snapshot yields identical results, but does not explicitly name alternative tools or exclusions, which is acceptable for a zero-parameter tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_statsADeterministic statistics. With a query: total matches + state distribution of the top results. Without: global knowledge-base stats (entry count, domains, snapshot).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional query to get coverage/state stats for | |
| domain | No | Optional domain filter (with query) |
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 useful context by explaining what 'stats' includes in each mode (entry count, domains, snapshot), and the word 'deterministic' reinforces the idempotent/read-only nature. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences to convey the dual-mode behavior. Every phrase adds value, and the most important distinction (query vs no query) is front-loaded. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (only two optional params, no output schema), the description covers the essential behavioral modes and key output concepts. It does not detail return formatting or pagination, but for a stats tool with read-only annotations, this is sufficient. Sibling tools are numerous but the description is self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds meaning beyond the schema by explaining the conditional effect of the optional query parameter (with vs without), and the schema already clarifies 'domain' as an optional filter. This supplemental context enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as providing deterministic statistics and explicitly differentiates two modes: with a query (total matches + state distribution) and without (global KB stats). This distinguishes it from the search and browse siblings by specifying it's about stats, not retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use each mode (with or without a query), implying usage in stats-gathering scenarios. It does not explicitly name alternatives or exclusions, but the mode-dependent behavior effectively guides the agent on when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
coldstate_verifyAVerify a previously-cited knowledge fact is unchanged. Provide the entry id and the content_hash you stored earlier; returns whether it still matches the current knowledge base. The trust primitive for AI-to-AI fact-checking.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable knowledge entry id | |
| content_hash | Yes | The content_hash from a previous fetch/cite |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent, and the description adds value by explaining the return behavior ('returns whether it still matches the current knowledge base') and framing it as a 'trust primitive.' This contextual information goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single purpose statement, a usage instruction, and a contextual tagline. Every sentence contributes meaning with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple verification tool with two well-documented parameters and safety annotations, the description covers the essentials: what it does, how to invoke it, and what it returns. The return behavior is described clearly, which is especially important given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (100% coverage), so the description adds little new semantic value. It reinforces that the content_hash should be from a previous fetch/cite, but does not introduce additional format, constraints, or examples beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Verify') and a specific resource ('previously-cited knowledge fact'). It also explains the mechanism (comparing content_hash) and distinguishes itself from sibling tools by its focus on verification rather than search or retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when you have an entry id and content_hash from an earlier cite and want to check if the fact is unchanged. It provides a use case ('AI-to-AI fact-checking') but does not explicitly name alternatives or exclusion criteria, which would have made it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
