Deterministic knowledge for AI agents: search, fetch, cite and verify a 48M-entry knowledge base.
Scored across 16 tools
Most tools have distinct targets: search vs search_global vs batch_search differ by scope and snapshot consistency, while resolve/fetch/cite/verify form a clear retrieval-and-verification lifecycle. Minor overlap remains among search, browse_documents, and stats-with-query, but descriptions should usually prevent misselection.
All tool names use the coldstate_ prefix and snake_case consistently, with predictable verb/noun or noun forms. No camelCase or competing conventions appear, and variants like search_global and batch_search fit the same pattern.
16 tools is slightly above the ideal range, but each maps to a distinct knowledge-infrastructure capability such as search, retrieval, citation, verification, or metadata. The set is not bloated enough to be confusing, though a few metadata tools could potentially be consolidated.
The core lifecycle—search, resolve, fetch, cite, verify, related/isomorph, and stats—is well covered for a deterministic knowledge server. Gaps include no visible index creation, ingestion, or update tools, so users cannot manage knowledge sources fully through this surface.
Run 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.
Browse documents in a ColdState index. Indexes are zero-knowledge, so each document is returned as your ref_id plus its state classification and E-score — no stored text. Map ref_id back to your own content.
| 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: indexes are zero-knowledge, so no stored text is returned — only ref_id, state classification and E-score — and the caller must map ref_id back to its own content. That is real context beyond the structured fields.
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?
Three short sentences, purpose front-loaded, with the surprising zero-knowledge return shape and the ref_id mapping action immediately following. No 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?
With no output schema, the description carries the burden of describing the return shape and does so well (ref_id, state classification, E-score). The only gap is pagination guidance, though limit/offset are self-documenting in the 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?
Schema description coverage is 100%, so limit, offset and index_id are already documented in the schema (including the idx_ pattern and default 20). The description adds nothing about parameter behavior, so baseline 3 applies.
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?
States a specific verb and resource ('Browse documents in a ColdState index'), which is legible against siblings like coldstate_search and coldstate_fetch. It stops short of explicitly contrasting itself with those siblings, so an agent must infer that this is unfiltered enumeration.
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?
Usage is only implied: 'Browse' suggests enumerating an entire index rather than issuing a query, but the description never says when to prefer this over coldstate_search or coldstate_list_indexes, nor does it state prerequisites (e.g., that the index must already exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Machine-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.
Get 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.
List 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.
Explain 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.
Fetch 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.
Cross-domain structural analog: given a knowledge entry id, find its closest structural twin in each OTHER domain ("same structure, different domain"). 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, idempotentHint and destructiveHint=false, so safety is covered. The description still adds behavioral value: 'Deterministic' signals reproducibly identical output for the same id, which is stronger than idempotency alone, and 'one per domain' sets the result shape. It omits failure behavior for unknown ids, so it is not fully exhaustive.
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?
Three short sentences, zero filler, front-loaded with the core action and scope before the tooling prerequisite. Every sentence 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?
With no output schema, the description carries the return-shape burden and does it: one structural twin per other domain. Annotations cover the safety profile. Only the unknown-id / empty-result behavior is left unspecified, a minor gap for a deterministic read tool.
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%: the id format (eng_.../soc_...) and the limit cap ('Max cross-domain analogs, one per domain') are already documented in the schema. The description's 'in each OTHER domain' reinforces the limit semantics slightly but adds no syntax or format detail beyond it, so the baseline 3 applies.
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?
States a specific verb+resource ('find its closest structural twin') and a precise scope ('in each OTHER domain'), with the gloss 'same structure, different domain' that immediately separates it from a same-domain relatedness tool. An agent can distinguish this from coldstate_related 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit prerequisite ('Use coldstate_resolve to turn a name into an id first') so the agent knows how to obtain the required id. It implicitly distinguishes itself from same-domain siblings via 'each OTHER domain' but never names an alternative or a when-not condition, so it stops short of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List 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.
Resolve 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.
Search 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.
Search 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.
Get 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.
Deterministic 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.
Verify 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
coldstate_batch_searchcoldstate_browse_documentscoldstate_capabilitiescoldstate_citecoldstate_domainscoldstate_explaincoldstate_fetchcoldstate_isomorphcoldstate_list_indexescoldstate_relatedcoldstate_resolvecoldstate_searchcoldstate_search_globalcoldstate_snapshotcoldstate_statscoldstate_verifyFree verified network knowledge for AI agents: deterministic answers, honest unknowns.
Deterministic fact verification for AI agents — checksums & curated data, not guesses.
Open scientific and engineering knowledge for AI agents: search, evidence, document publishing.
Evidence-grounded, graph-connected, correctable memory for agents.
Add one secure layer between your agents and this server.
