ai-agent-channel

pin_list

Read-only

Retrieve an overview of all pinned entries with key, title, version, and update details to verify local document copies in one call, without bodies.

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, where one character can take several bytes. 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.8/5.0

Behavior5/5

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

The description goes well beyond the readOnlyHint annotation. It discloses that the tool returns no bodies, that every pin response carries body_sha256 and length fields, and it explains the exact hashing semantics (raw UTF-8 bytes, no normalisation) and the ambiguity rationale for two length fields. It also clarifies that the server publishes these values but does not verify them, which is important behavioral context for an agent deciding whether to trust the values.

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 description is front-loaded with the core purpose and the no-bodies caveat, then expands into hash/length semantics. The first two sentences are tight and high-value. The later sentences about hashing and length are somewhat verbose but earn their place because they explain non-obvious behavior that an agent needs to interpret the response correctly.

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

Completeness5/5

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

For a parameterless list tool with an output schema and readOnlyHint annotation, the description is complete. It covers what the tool returns, what it does not return, how to get bodies, and how to interpret the hash and length fields. The only minor gap is that it doesn't mention pagination or ordering, but the description explicitly frames this as a cheap one-call overview, so that omission is not material.

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?

The tool has zero parameters, so the schema provides no parameter semantics to clarify. The description compensates by explaining what the response contains and how to interpret the hash/length fields, which is the closest analogue to parameter semantics for a parameterless tool. A 4 is appropriate because there are no parameters to document, and the description adds meaningful context about the returned fields.

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?

The description states a specific verb ('List') and resource ('all pinned entries') and enumerates the exact fields returned (key, title, version, updated_by, updated_at, approved_by). It also explicitly distinguishes itself from pin_get by noting that bodies are excluded, so an agent can tell this tool apart from its sibling without opening schemas.

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?

The description explicitly says when to use this tool: for a cheap overview and to verify a local copy of every document in one call. It also names the alternative, pin_get(key), for fetching a body. This is clear usage guidance with an explicit exclusion and alternative.

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