ColdState Knowledge Search

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: consistent kb_snapshot and ranked results per query, enhancing understanding beyond 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?

Two sentences front-loaded with core purpose and benefit. No unnecessary words, efficient.

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 no output schema, description provides high-level return info but lacks details on error handling, result ordering, or pagination. Adequate but could be more complete for AI agent to fully understand output.

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 schema already documents all parameters. Description does not add parameter-specific meaning beyond the schema, 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?

Specific verb 'run' with clear resource 'knowledge-base queries in one call against a single consistent kb_snapshot'. Distinguishes from sibling tools like coldstate_search by emphasizing batch and consistency.

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?

States it's efficient and snapshot-consistent for batch queries, implying use when multiple queries need consistency. Does not explicitly name alternatives but provides clear context for when to use.

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

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

Annotations declare readOnlyHint/idempotentHint, so the description adds valuable behavioral context by detailing the return payload structure (titles, snippets, content, state classification, E-scores). It does not contradict annotations. It could improve by mentioning pagination behavior or rate limit implications of large offsets.

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 sentences with zero waste: first establishes the action and scope, second details the return values. Every word earns its place and the description is appropriately 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?

Given the simple 3-parameter structure, good annotations, and lack of output schema, the description adequately compensates by detailing the return fields. It appropriately omits redundant pagination explanations (covered by schema) but could mention whether browsing is ordered or filtered by default.

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%, providing full documentation for index_id, limit, and offset. The description references 'ColdState index' which maps to the index_id parameter, but otherwise relies on the schema for parameter semantics, meeting the baseline for high-coverage schemas.

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?

Description uses specific verb 'browse' with clear resource 'documents' and scope 'ColdState index'. The verb choice implicitly distinguishes from sibling 'search' tools, and listing specific return fields (titles, snippets, E-scores) clarifies exactly what data is accessed.

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 verb 'browse' provides implied differentiation from sibling 'search' tools (coldstate_search, coldstate_search_global), suggesting use for exploration/listing versus querying. However, it lacks explicit when-to-use guidance or stated prerequisites (e.g., needing a valid index_id from list_indexes first).

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds useful context about the content of the manifest (determinism guarantees, limits) beyond safety traits.

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 concise sentences: first describes content, second gives usage instruction. 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?

The description is complete for a simple zero-parameter tool with annotations. It lists key fields but lacks output schema structure; still adequate given the tool's nature.

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?

No parameters exist, and the description is not required to add param details. It explains the output instead, which is sufficient.

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 specifies exactly what the tool returns ('available tools, knowledge domains, current kb_snapshot, determinism guarantees, and limits') and instructs to call it first, clearly distinguishing it from sibling 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?

Explicitly states 'Call this first to self-configure,' providing a clear directive on when to use this tool as an initialization step.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds that the citation is canonical and reproducible, and lists included fields. No additional behavioral traits like auth or rate limits are disclosed, but the description complements annotations well.

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 tight sentences. The first specifies action and output fields, the second explains the use case. No redundant words; every sentence serves a purpose.

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 tool with one parameter and no output schema, the description adequately explains purpose and ties to verification. It could elaborate on what 'canonical' means operationally, but overall is sufficient given 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?

Schema coverage is 100% for the id parameter with a description. The description adds meaning by stating the id identifies a knowledge entry and enumerating the citation fields, providing context beyond the schema.

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 gets a canonical, reproducible citation for a knowledge entry by id, listing specific fields and linking to coldstate_verify. It differentiates from sibling tools like coldstate_fetch by focusing on citation generation.

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 explicitly instructs to use for citing facts to enable later verification with coldstate_verify. It provides clear context but does not mention when not to use or compare to other siblings beyond coldstate_verify.

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

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 that the tool returns 'entry counts' alongside domains, which provides useful payload context not in annotations. However, it omits details about return format, pagination, or what constitutes an 'entry'.

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?

Single sentence with zero waste. Front-loaded with action verb ('List'), followed by resource identification, scope qualifier ('ColdState's global knowledge base'), and key behavioral detail ('with entry counts'). Every clause 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?

Given zero parameters and read-only annotations covering safety profile, the description adequately covers the tool's purpose and key return characteristic (entry counts). Lacks output schema specification, but 'entry counts' provides sufficient hint for a simple listing operation of this complexity.

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?

Input schema has zero parameters (empty object), establishing baseline 4 per rubric. The description correctly omits parameter discussion since none exist, and requires no compensation for missing schema documentation.

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?

Description uses specific verb 'List' with clear resource 'knowledge domains in ColdState's global knowledge base' and distinguishes from siblings by focusing on 'domains' versus documents, indexes, or search operations. The addition of 'with entry counts' specifies the scope of returned data.

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?

Description implies usage (retrieving domain inventory with counts) but provides no explicit guidance on when to use this versus siblings like coldstate_search or coldstate_browse_documents. No 'when-not' or alternative recommendations are provided.

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

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

Annotations already indicate readOnly and idempotent, and the description adds 'deterministic and reproducible', which provides additional behavioral context beyond annotations. No contradictions.

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 sentences: the first states the core purpose, the second adds return value details and behavioral property. No redundant words, front-loaded.

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 no output schema, the description explains what the tool returns (per-term relevance breakdown and overall match summary), which is sufficient for an agent to understand the output. Combined with annotations and schema, the tool is well-defined.

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 the schema already documents all three parameters. The description does not add further meaning about parameter values or usage beyond what's in the schema.

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 it explains why a document ranked for a query, using a specific verb and resource. It distinguishes from siblings like 'coldstate_search' and 'coldstate_browse_documents' by focusing on explanation rather than retrieval or browsing.

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 implicitly conveys when to use (to get per-term relevance and match summary for a specific doc-query pair) but does not explicitly mention when not to use or suggest alternatives. However, the context of siblings makes the use case clear.

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

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

Annotations already indicate idempotent and read-only. The description adds that retrieval is deterministic and returns content_hash and kb_snapshot, providing useful behavioral context beyond 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?

Two sentences, front-loaded with the action. No extra words. Every sentence adds value 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?

Given one parameter, rich annotations, and no output schema, the description fully explains the tool's purpose, usage, and output format (full record, content_hash, kb_snapshot). No gaps.

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 schema covers the id parameter with 100% description (min/max length). The tool description adds that the id is 'stable' and gives example formats (eng_..., soc_...), adding meaning beyond the schema.

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 fetches a single knowledge-base entry by stable id. It uses a specific verb 'Fetch' and distinguishes from siblings like coldstate_search by emphasizing verbatim deterministic 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 implies use when you have a stable id, but does not explicitly state when to use this tool vs alternatives like coldstate_search. No exclusions or when-not guidance provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool is deterministic and uses embedding-cluster similarity, providing behavioral insight beyond annotations. No contradiction.

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 sentences, front-loaded with the core purpose, and a useful usage tip. No redundant information. Highly efficient.

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 low complexity (2 parameters, no output schema), the description adequately covers the tool's behavior, method, and a prerequisite step. A brief note on the return format would push it to 5, but not essential.

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 baseline is 3. The description does not add new meaning beyond what the schema already provides for each parameter. It simply reiterates the context.

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?

Description clearly states the tool's action: given a knowledge entry id, find its closest structural twin in each OTHER domain via embedding-cluster similarity. It distinguishes from siblings by mentioning coldstate_resolve for name-to-id conversion.

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?

Explicitly guides to use coldstate_resolve first when needed. Implicitly indicates use case (cross-domain analogs) but does not explicitly exclude alternative tools like coldstate_related. Still, the guidance is clear and helpful.

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

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

Annotations establish read-only/idempotent safety profile. Description adds valuable behavioral context by disclosing return payload structure (status, mode, document count, domain preset), which compensates for missing output schema. Does not mention pagination, rate limits, or auth requirements.

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?

Single sentence with front-loaded verb. Every clause earns its place: 'all your' establishes scope, and the four field specifications provide necessary return-value documentation without redundancy. No 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?

Adequate for a zero-parameter read operation. Field enumeration provides sufficient compensation for missing output schema. Annotations cover safety properties. Minor gap: does not specify return type structure (array vs object) or pagination behavior.

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?

Zero parameters present. Per scoring rules, 0 params = baseline 4. No parameter semantic enrichment required or possible.

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?

Clear verb ('List') and resource ('ColdState indexes') with specific scope ('all'). Enumerating return fields (status, mode, document count, domain preset) implicitly distinguishes this metadata listing from document-oriented siblings like search/browse, though explicit differentiation from coldstate_domains is absent.

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 explicit when-to-use guidance or alternative recommendations provided. Given siblings include coldstate_domains and various search tools, the description misses opportunity to clarify whether to use this for inventory vs. domain management or when to prefer search over listing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds determinism and idempotency ('Same id → same neighbors') and describes the output structure (relation and cross_domain flag), which is valuable beyond 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 clear, front-loaded sentences. No redundant information. Every sentence adds value.

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 no output schema, the description adequately explains the return type (entries with relation and cross_domain flag) and deterministic behavior. The tool's purpose and parameters are well-covered.

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%, with both parameters having brief descriptions. The tool description adds no additional parameter information, so it meets the baseline but does not enhance 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 states the tool finds knowledge entries deterministically related to a given entry id via a concept-cluster graph. It specifies the resource, action, and method, distinguishing it from sibling tools like coldstate_search 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 description implicitly guides usage by focusing on related entries, but it does not explicitly state when to use or avoid this tool compared to siblings. The context from sibling tool names helps, but explicit guidance would improve clarity.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds determinism and match logic (exact title match vs top relevance), supplementing the annotations with algorithmic detail. No contradictions.

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 sentences, each serving a purpose: purpose, determinism, return, and usage. No fluff, front-loaded, efficiently 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?

Covers key aspects: purpose, deterministic behavior, return (canonical + alternatives), and next steps. Without an output schema, it could detail the alternatives format, but overall sufficient for the tool's simplicity.

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%, so baseline is 3. Description adds context that query is a name/alias/surface form, but adds no new detail for the limit parameter. Meets baseline but no significant added value.

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 resolves a name/alias/surface form to a canonical ColdState knowledge entry with id and title. It distinguishes from siblings by specifying the deterministic matching and follow-up tools (coldstate_fetch/coldstate_related).

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?

Provides clear context: use for resolving names to canonical entries, and advises using returned id with coldstate_fetch/coldstate_related. However, does not explicitly compare to siblings like coldstate_search, nor state when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, non-destructive behavior. Description adds value by detailing the return format (Ψ scores, state classification) which is not in 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?

Two sentences, front-loaded with purpose, includes essential constraint. No wasted words. Eminently scannable.

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?

No output schema, but description explains return fields. While missing explicit behavior when both collection and index_id are provided, the mutual exclusivity statement implies an error. Given 5 parameters, the description covers enough for effective use.

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%, but description adds critical constraint of mutual exclusivity between 'collection' and 'index_id', which is not enforced by schema. Also describes return fields that map to query results, adding meaning beyond property types and descriptions.

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?

Description clearly states verb 'Search', resource 'ColdState index', and specifies return values (ranked results, Ψ scores, state classification). Distinguishes from sibling 'coldstate_search_global' by indicating this searches a specific index.

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?

Explicitly states the mutual exclusivity constraint: 'Provide exactly one of `collection` or `index_id`'. However, does not directly compare to sibling tools or specify when to use this vs alternatives.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds value by specifying deterministically ranked results, Ψ relevance scores, and state classification, which are behavioral details beyond the annotations. No contradiction found.

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 core purpose, and includes only essential details. No extraneous text, making it highly efficient for an AI agent to parse.

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 no output schema, the description covers return format (ranked results, relevance scores, state classification) and mentions domain filtering. It lacks explanation of pagination or state classification meaning, but is largely complete for a search tool with well-documented 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 coverage is 100%, so the description adds little beyond repeating the optional domain filter. No new contextual information about parameters is provided beyond what the schema already contains.

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 ('Search') and the resource ('ColdState's global knowledge base'), providing specific scope (48.4M+ entries across 35 domains) and differentiating from siblings like 'coldstate_search' by emphasizing global coverage and domain filtering.

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 usage for global searches but does not explicitly state when to use this tool over alternatives like 'coldstate_search' or when filtering is recommended. No exclusions or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the purpose for reproducibility and that identical queries yield identical results, going beyond the annotations.

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

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

Two concise sentences. Front-loaded: first sentence states purpose, second provides usage tip. No unnecessary 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?

With no parameters and no output schema, the description sufficiently explains the tool's purpose and usage. Could optionally mention the ID format, but not essential. Annotations cover safety.

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?

There are no parameters, and schema coverage is 100%. Description adds no parameter info, which is appropriate. Baseline 4 for zero parameters.

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?

Description clearly states it returns the current knowledge-base snapshot/version ID for reproducibility purposes. It uses specific verb 'Get' and resource 'snapshot/version id', and is distinct from sibling tools which perform queries, browsing, etc.

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?

Explicitly mentions pinning the snapshot for reproducibility, providing a clear usage context. No alternatives or exclusions needed given its unique function.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by stating the tool is deterministic and detailing the output format for both modes, which enhances understanding beyond 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 concise sentences, front-loaded with 'Deterministic statistics' which immediately conveys the tool's nature. Every word is purposeful with no 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?

Given the tool's simplicity (two optional parameters, no output schema), the description fully explains both modes and their outputs. It covers return values adequately, making the tool's functionality complete for an agent.

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 parameters. The tool description reinforces but does not add significant new meaning beyond the schema, meeting the baseline for adequate 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 clearly states the tool provides deterministic statistics, with specific output for query mode (total matches + state distribution) and without (global stats: entry count, domains, snapshot). This distinguishes it from sibling search tools like coldstate_search which return individual results.

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 explicitly separates use cases for query and no-query modes, providing clear context for when to use each. However, it does not explicitly state when not to use this tool or name alternatives, keeping it from a perfect score.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return value info (whether it matches). Could further clarify behavior on missing id or hash mismatch, but solid.

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 sentences: first explains action and inputs/outputs, second positions tool as trust primitive. No wasted words, front-loaded.

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?

Covers purpose, inputs, and return concept. Lacks explicit error cases (e.g., id not found) but given no output schema and simplicity, it's nearly 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?

Schema covers both params with descriptions. Description adds 'you stored earlier' hinting that content_hash comes from prior fetch, adding slight context beyond schema.

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?

Clearly states the tool verifies a previously-cited fact is unchanged, using entry id and content_hash. It is distinct from sibling tools like coldstate_fetch or coldstate_cite by focusing on integrity checking.

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?

Provides clear context: use when you have a stored content_hash and need to confirm it matches current knowledge base. Does not explicitly exclude alternatives but the trust primitive framing guides usage.

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