hashn

compare_instances

Read-only

Compare two or more instances of one convention side by side (0.63.0): for each dimension of that convention, each one's value, and whether they agree. Where they agree there is nothing to decide; what differs is the point of contention. refs: <workspace_id>/<path>[@<receipt>] (listings, deliveries, project or team files, a file at a cited save), or convention names with decision_convention 'convention' (deciding which convention frames two things), or plain values with a decision_convention. It is inferred when every ref names the same convention. With dimensions, only those rows. Use it to write a decision file (/docs/decisions); hashn compares, it never picks. frame is the 0.63.0 name of decision_convention.

Input Schema

Name	Required	Description
`refs`	Yes	Two to twelve things to compare: '<workspace_id>/<path>' (optionally '@<receipt>' for a cited save), convention names when frame is 'convention', or plain values with a frame.
`frame`	No	The 0.63.0 name of decision_convention; prefer that.
`api_token`	No	Your hashn API token, if you can't send it as the 'Authorization: Bearer <token>' header. Omit it when the header is set.
`dimensions`	No	Optional: compare on these dimensions only, e.g. a child decision's proposed children.
`decision_convention`	No	The convention every ref is an instance of (or 'convention' to compare conventions). Omit to infer it when all refs name the same convention.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 25, 2026

addedInput schema / properties / decision_convention

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The convention every ref is an instance of (or 'convention' to compare conventions). Omit to infer it when all refs name the same convention.",
+  "title": "Decision Convention"
+}

changedInput schema / properties / frame / description

Previous value: -"The convention every ref is an instance of (or 'convention' to compare conventions). Omit to infer it when all refs name the same convention."New value: +"The 0.63.0 name of decision_convention; prefer that."

AddedOct 25, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful behavioral context such as the comparison output concept, inference of the convention, and the fact that it never makes a decision. It does not cover auth, rate limits, or exact response shape, but those gaps are smaller given 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.

Conciseness4/5

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

The core purpose is front-loaded and most sentences carry useful information. The refs sentence is long and parenthetical, reducing readability, but the overall length is reasonable for a complex comparison tool.

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

Completeness4/5

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

For a read-only, no-output-schema tool with five parameters, the description sufficiently explains what is compared, how refs and frames work, when the convention is inferred, and how dimensions narrow results. It does not specify the exact response shape, but the conceptual output is clear enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is already high, and the description adds meaning for refs by listing accepted forms such as listings, deliveries, project/team files, cited saves, convention names, and plain values. It also explains the inference rule for decision_convention and the filtering effect of dimensions, though some parameter detail duplicates the schema.

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

Purpose4/5

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

The description clearly states a specific verb and resource: compare instances of one convention side by side, returning each dimension's value and whether they agree. It does not explicitly contrast with named siblings, but its role is distinguishable from decision-making tools through 'hashn compares, it never picks.'

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

Usage Guidelines4/5

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

It provides a clear usage context: use it to write a decision file under /docs/decisions, and notes that differences are the point of contention. It also implies a boundary by saying it never picks, but it does not name alternative tools or explicit when-not-to-use conditions.

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

All hashn tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?