Uoink 3.12.0 / tool reference

pin_shelf

Record a user's pin, unpin or move decision for one item's shelf membership.

Inputs

video_idRequired: text
shelf_idRequired: text
actionRequired: one of: pin, unpin, move
expected_projection_revisionRequired: whole number
operation_keyRequired: text
user_intent_tokenRequired: text
reasonOptional: text

Full input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "client": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "hash": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "token": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{43,128}$"
    },
    "revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "evidence": {
      "type": "object",
      "properties": {
        "basis": {
          "type": "string",
          "enum": [
            "packet",
            "fetched_full"
          ]
        },
        "kind": {
          "type": "string",
          "enum": [
            "timed_clip",
            "text_only"
          ]
        },
        "excerpt_id": {
          "$ref": "#/$defs/hash"
        },
        "card_hash": {
          "$ref": "#/$defs/hash"
        },
        "quote": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000
        }
      },
      "required": [
        "basis",
        "kind",
        "excerpt_id",
        "card_hash",
        "quote"
      ],
      "additionalProperties": false
    },
    "membership": {
      "type": "object",
      "properties": {
        "shelf_id": {
          "$ref": "#/$defs/id"
        },
        "shelf_path": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "minItems": 1,
          "maxItems": 3
        },
        "confidence": {
          "$ref": "#/$defs/confidence"
        },
        "evidence": {
          "$ref": "#/$defs/evidence"
        }
      },
      "required": [
        "shelf_id",
        "shelf_path",
        "confidence",
        "evidence"
      ],
      "additionalProperties": false
    },
    "result": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "outcome": {
              "const": "assigned"
            },
            "memberships": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/membership"
              },
              "minItems": 1,
              "maxItems": 3
            }
          },
          "required": [
            "outcome",
            "memberships"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "outcome": {
              "type": "string",
              "enum": [
                "unmapped",
                "unsupported",
                "error"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "required": [
            "outcome",
            "reason"
          ],
          "additionalProperties": false
        }
      ]
    },
    "usage": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "status": {
              "const": "reported"
            },
            "model": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "input_tokens": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "output_tokens": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "cache_read_tokens": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "cache_create_tokens": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "wall_time_ms": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            }
          },
          "required": [
            "status",
            "model",
            "input_tokens",
            "output_tokens",
            "wall_time_ms"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "status": {
              "const": "unavailable"
            },
            "model": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "wall_time_ms": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            }
          },
          "required": [
            "status",
            "reason"
          ],
          "additionalProperties": false
        }
      ]
    }
  },
  "type": "object",
  "properties": {
    "video_id": {
      "$ref": "#/$defs/id"
    },
    "shelf_id": {
      "$ref": "#/$defs/id"
    },
    "action": {
      "type": "string",
      "enum": [
        "pin",
        "unpin",
        "move"
      ]
    },
    "expected_projection_revision": {
      "$ref": "#/$defs/revision"
    },
    "operation_key": {
      "$ref": "#/$defs/key"
    },
    "user_intent_token": {
      "$ref": "#/$defs/token"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "video_id",
    "shelf_id",
    "action",
    "expected_projection_revision",
    "operation_key",
    "user_intent_token"
  ],
  "additionalProperties": false
}

Outputs and behavior

Record a user's pin, unpin or move decision for one item's shelf membership. Use for an explicit individual decision; use apply_reshelving for run-wide proposed changes. Requires a dashboard-minted user_intent_token tied to the exact operation and current projection revision; no actor string grants authority. The Librarian cannot override the resulting user decision. Retry the same operation_key only with identical arguments.

The registry does not publish an output schema for this tool. The description above is its documented behavior; response fields beyond it are not specified here.

Example call

Example tool name and arguments, generated from the input schema. Replace placeholder strings and sample numbers with your own values. This is a request template, not a recorded call or response.

{
  "name": "pin_shelf",
  "arguments": {
    "video_id": "YOUR_VIDEO_ID",
    "shelf_id": "YOUR_SHELF_ID",
    "action": "pin",
    "expected_projection_revision": 0,
    "operation_key": "YOUR_OPERATION_KEY",
    "user_intent_token": "REPLACE_WITH_REAL_TOKEN____________________"
  }
}

Clients

This tool is available to MCP clients using stdio or http.

The registry records transport support, not individual client test results. See the MCP setup reference for named clients, configuration, and tool-list limits.

Set up your client All MCP tools

Source

Uoink 3.12.0 tool registry. Synced 2026-10-30.

Synced tool manifest / Registry at source commit 318fd0c