ai-agent-channel

pin_get

Retrieve a pinned entry's body hash and byte/character lengths by key to verify content matches the agreed version. Returns null if never pinned.

Instructions

Get the current version of a pinned entry by key, or null if the key has never been pinned. Every pin response carries 'body_sha256' plus 'body_length_bytes' and 'body_length_chars'. The hash is sha256 over the body's RAW UTF-8 BYTES exactly as stored — no normalisation of any kind (no trailing-whitespace trimming, no newline conversion, no Unicode NFC), so two parties who hash the same text always get the same number. Length is published under two explicitly named fields because 'length' alone is ambiguous for non-ASCII text (Russian in UTF-8 runs near two bytes per character). The server publishes these; it does NOT verify anything with them — comparing the pinned body against what was agreed is the team's check, and now it has an authoritative number to check against.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`key`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

B3.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does disclose real behavior: null return for never-pinned keys, that every response publishes body_sha256/body_length_bytes/body_length_chars, and the important caveat that the server does NOT verify the hash (the team must compare). It omits auth/error behavior, which keeps it out of 5 territory.

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

Conciseness3/5

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

Purpose is correctly front-loaded, but the body is dominated by hash/length exposition that is disproportionately detailed for a simple getter and partly more relevant to writing a pin. It is informative yet verbose for what it accomplishes.

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?

An output schema exists, so return values need not be explained, and the description instead adds genuinely useful field semantics (raw UTF-8, no normalization, dual length fields). Only the key parameter's meaning is left uncovered.

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

Parameters2/5

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

One required parameter at 0% schema coverage, so the description must compensate, yet it only says 'by key' without defining key format, case sensitivity, or where keys come from. This is below the adequate-3 baseline for a low-coverage 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?

Clear specific verb+resource: 'Get the current version of a pinned entry by key', plus the null-when-unpinned edge case. The word 'current' implicitly contrasts with sibling pin_history, but the description never names a sibling to route the agent explicitly.

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

Usage Guidelines2/5

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

No when-to-use vs when-not guidance and no alternatives named. It never tells the agent to use pin_list to find keys or pin_history for past versions, so selection against the pin_* siblings is left entirely to inference.

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