ai-agent-channel

pin_list

List pinned entries without bodies for a cheap overview, including hashes and byte/char lengths to verify local copies and check agreement across roles.

Instructions

List all pinned entries (key, title, version, updated_by, updated_at, approved_by) WITHOUT bodies — cheap overview, and enough to verify your local copy of every document in one call. Use pin_get(key) to fetch a body. 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
No arguments

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.4/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 behavioral burden and delivers: it discloses that bodies are omitted, that every response carries body_sha256 plus two length fields, the exact hashing contract (sha256 over raw UTF-8 bytes, no normalisation), and critically that the server does NOT verify — verification is the team's job. It stops short of covering pagination or access/permission behaviour, so a 4 rather than 5.

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?

Core purpose, returned fields and the pin_get hand-off are front-loaded and efficient. The back half, however, is dense and repetitive — the parenthetical list of what is not normalised, the Russian-UTF-8 aside, and the closing sentence restating that the server publishes but does not verify, which was already implied.

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 fully re-explained, yet the description usefully documents the hash and dual-length semantics that a schema alone would not make actionable. For a zero-param lister with an output schema, an agent has everything it needs to call it correctly; only edge behavior like pagination is absent.

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?

Zero parameters, so the baseline is 4; the schema is trivially complete and the description adds nothing to compensate for. The reference to pin_get(key) is about the sibling, not this tool's own inputs.

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

Purpose5/5

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

States a specific verb and resource ('List all pinned entries') and enumerates the exact fields returned, plus the key differentiator — 'WITHOUT bodies — cheap overview'. It explicitly contrasts itself with the sibling pin_get, so an agent can route between them 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.

Usage Guidelines5/5

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

Gives explicit when-to-use ('cheap overview... enough to verify your local copy of every document in one call') and names the alternative for the other case ('Use pin_get(key) to fetch a body'). Nothing is left to inference.

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