ai-agent-channel

pin_set

Create or update a channel-level pinned entry by stable key, keeping prior versions in history. Pass dry_run to preview approval checks before writing.

Instructions

Create or update a channel-level pinned entry (charter, glossary, contract version) by stable key. Previous versions are kept — see pin_history. Reserved keys by convention: 'team-charter', 'glossary', 'contract-version'. Updating an EXISTING pin under a protected key requires 'approved_by': the id of a proposal message that (a) names the pin key — via its 'pin_key' field (preferred) or anywhere in its topic/body (legacy fallback), (b) carries an 'agree' acknowledgement newer than the current pin version — in a channel with more than two roles, an 'agree' from EVERY role except the proposer (a pin is a channel-level contract; acknowledge works on messages addressed to others too), and (c) has not approved a pin update before — one agreed proposal, one change. Protected = the reserved keys above PLUS any key that has ever been updated with approved_by: once a pin is contractual it stays contractual. For reserved keys approved_by is required for the FIRST version too (bootstrap = one proc + agree per key); free first-time creation exists only for non-reserved keys, and passing approved_by there protects the key from then on. Etiquette: the pin body must be VERBATIM the text agreed in the proposal. The server does not enforce that, but it does publish the numbers to check it with. Pass dry_run=true to run EVERY check above and get back {ok, problem, missing_agrees} without writing anything — the same code path as the real call, so the preview cannot disagree with it. Use it before starting a round of votes, and again before the real write. 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
`body`	No
`title`	Yes
`dry_run`	No
`version`	Yes
`body_ref`	No
`approved_by`	No

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.3/5.0

Behavior3/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 a lot the schema cannot: version history retention, protected-key escalation semantics, dry_run running the identical code path, and the exact meaning of body_sha256/body_length_bytes/body_length_chars. It does not state auth/permission requirements or rate limits, and much of its length is governance policy rather than behaviour of the call itself.

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?

The purpose and key constraints are front-loaded, which is good, but the text is one very dense paragraph running well over 200 words with redundant restatement (e.g. the server publishes but does not verify the numbers is stated twice). Much earns its place, but tighter grouping of approval rules, hash semantics and dry_run would read better.

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?

An output schema exists, so return values needn't be explained, yet the description goes further and tells the agent what fields to expect. For a mutation with an intricate approval contract and no annotations, this covers everything an agent needs to invoke it correctly, short of the two unexplained params.

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?

Schema coverage is 0%, so the description must compensate, and it does for key (stable key, reserved values), approved_by (id of a proposal message with three named conditions), dry_run (preview, no writes) and body (must be verbatim text agreed). However body_ref and title are never explained, leaving two of seven parameters undocumented in both schema and description.

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 opening sentence gives a specific verb and resource ('Create or update a channel-level pinned entry... by stable key') and gives concrete content examples (charter, glossary, contract version). It explicitly routes to pin_history for prior versions, so an agent can separate this from pin_get/pin_list/pin_history at a glance.

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?

Usage is spelled out explicitly: use dry_run=true before starting a round of votes and again before the real write, and approved_by is required for reserved/protected keys including bootstrap. It names the alternative for history (pin_history) and defines exactly when the approval path applies versus free first-time creation for non-reserved keys.

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