Every tool is registered through defineTool. This page is the contract: argument shape, canonical output shape, which token it needs, whether it is destructive, and its presentation card kind.

Conventions:

args are the model-facing parameters (validated by defineTool).
output is the canonical JSON value returned by execute. output.render is noted only when it produces non-trivial prose.
Token — C = community, U = user (admin). C+U means it works with either but the user token gives more fields.
Destructive — ✗ read-only, ⚠ mutates state, ⚠⚠ hard to undo (ban, delete, settings change).
Card — the presentCall/presentResult card kind from the DSH presentation vocabulary.

Community

`vk_community_info`


Token	C+U
Destructive	✗
Card	`generic`

args: { fields?: string[] }
output: {
  groupId: number
  name: string
  screenName: string
  type: 'group'|'page'|'event'
  isClosed: 0|1|2
  isAdmin: boolean
  adminLevel: 0|1|2|3       // 0 = not admin
  membersCount: number
  wall: 0|1|2|3
  description: string
  photo200: string
  scopesAvailable: string[] // from groups.getTokenPermissions
  counters: Record<string, number>
}

`vk_community_update`


Token	C (admin_level 3)
Destructive	⚠⚠
Card	`generic`

args: {
  dryRun?: boolean          // default: config.safety.dryRunDefault → true
  fields: Partial<{
    title: string
    description: string
    screenName: string
    website: string
    publicCategory: number
    ageLimits: 1|2|3
    wall: 0|1|2|3
    messages: boolean
    photos: boolean
    videos: boolean
    audio: boolean
    docs: boolean
    topics: boolean
    wiki: boolean
    market: boolean
    mainSection: 0|1|2|3|4|5
  }>
}
output: {
  dryRun: boolean
  changes: Array<{ field: string; from: unknown; to: unknown }>
  applied: boolean          // false when dryRun
}

presentResult renders a diff card listing changed fields. Pre-execute gate forces ask when dryRun is false.

Members

`vk_members_list`


Token	U
Destructive	✗
Card	`generic`

args: {
  sort?: 'id_asc'|'id_desc'|'time_asc'|'time_desc'
  offset?: number           // default 0
  count?: number            // default 100, max 1000
  fields?: string[]         // 'photo_100','sex','bdate','city','country','last_seen'
  filter?: 'friends'|'unsure'|'managers'|'donuts'
}
output: {
  items: Array<{ id: number; firstName: string; lastName: string; photo100?: string; role?: string }>
  total: number
  offset: number
  count: number
  hasMore: boolean
}

`vk_members_manage`


Token	C (admin)
Destructive	⚠
Card	`generic`

args: {
  action: 'approve'|'reject'|'invite'|'remove'
  userIds: number[]         // max 500
}
output: {
  results: Array<{ userId: number; ok: boolean; error?: string }>
  totalRequested: number
  totalSucceeded: number
}

Packs up to 25 calls per execute request.

`vk_member_status`


Token	C+U
Destructive	✗
Card	`generic`

args: { userIds: number[] }
output: Array<{
  userId: number
  isMember: boolean
  memberStatus: 0|1|2|3|4|5
  banInfo?: { endDate: number; comment: string } | null
}>

Moderation

`vk_ban_list`


Token	U
Destructive	✗
Card	`generic`

args: {
  offset?: number           // default 0
  count?: number            // default 100, max 200
  fields?: string[]
}
output: {
  items: Array<{ id: number; type: 'profile'|'group'; banInfo: { endDate: number; comment: string } }>
  total: number
  hasMore: boolean
}

`vk_ban_manage`


Token	C (admin)
Destructive	⚠⚠
Card	`generic`

args: {
  action: 'ban'|'unban'
  userIds: number[]         // max 500
  reason?: number           // 0 other, 1 spam, 2 verbal abuse, 3 foul language, 4 irrelevant messages, 5 other
  comment?: string
  commentVisible?: boolean  // default false
  endDate?: number          // unix timestamp, 0 = permanent
}
output: {
  results: Array<{ userId: number; ok: boolean; error?: string }>
  totalRequested: number
  totalSucceeded: number
}

Pre-execute gate forces ask.

`vk_requests_list`


Token	C+U
Destructive	✗
Card	`generic`

args: { offset?: number; count?: number; fields?: string[] }
output: {
  items: Array<{ id: number; firstName: string; lastName: string; photo100?: string; date: number }>
  total: number
  hasMore: boolean
}

`vk_requests_handle`


Token	C (admin)
Destructive	⚠
Card	`generic`

args: { action: 'approve'|'reject'; userIds: number[] }   // max 500
output: { results: Array<{ userId: number; ok: boolean; error?: string }>; totalSucceeded: number }

Managers

`vk_managers_list`


Token	C (admin)
Destructive	✗
Card	`generic`

args: { fields?: string[] }
output: Array<{
  userId: number
  role: 'creator'|'administrator'|'editor'|'moderator'
  permissions: Record<string, boolean>
  firstName: string
  lastName: string
}>

`vk_manager_set`


Token	C (creator only)
Destructive	⚠⚠
Card	`generic`

args: {
  userId: number
  role: 'administrator'|'editor'|'moderator'
  permissions?: Partial<{
    wall: boolean
    messages: boolean
    docs: boolean
    wiki: boolean
    photos: boolean
    stories: boolean
    market: boolean
    groups: boolean
    topics: boolean
    advertisers: boolean
    contacts: boolean
    analytics: boolean
    monetization: boolean
    live: boolean
  }>
  action: 'appoint'|'dismiss'
}
output: { userId: number; ok: boolean; role: string; error?: string }

Pre-execute gate forces ask.

Wall

`vk_wall_post`


Token	C
Destructive	⚠
Card	`diff` (creates a post)

args: {
  message: string
  attachments?: string[]            // attachment strings from vk_media_upload
  fromGroup?: boolean               // default config.defaultFromGroup → true
  signed?: boolean                  // default config.defaultSigned → false
  publishDate?: number              // unix timestamp → postponed post
  guid?: string                     // idempotency key; plugin auto-generates if absent
  lat?: number
  long?: number
  closeComments?: boolean
  copyright?: string
}
output: { postId: number; ownerId: number; url: string; postponed: boolean }

presentCall renders a diff card with the new post text; presentResult adds the canonical VK URL.

`vk_wall_edit`


Token	C
Destructive	⚠
Card	`diff`

args: {
  postId: number
  message?: string
  attachments?: string[]
  lat?: number
  long?: number
  copyright?: string
  closeComments?: boolean
}
output: { postId: number; ok: boolean; error?: string }

`vk_wall_delete`


Token	C
Destructive	⚠⚠
Card	`generic`

args: { postIds: number[]; tombstone?: boolean }   // tombstone=true → wall.closeComments + report spam before delete
output: { results: Array<{ postId: number; ok: boolean; error?: string }> }

Pre-execute gate forces ask.

`vk_wall_pin`


Token	C (admin)
Destructive	⚠
Card	`generic`

args: { postId: number; action: 'pin'|'unpin' }
output: { postId: number; ok: boolean; pinned: boolean }

`vk_wall_list`


Token	C+U
Destructive	✗
Card	`generic`

args: {
  filter?: 'owner'|'others'|'all'|'postponed'|'suggested'   // default 'owner'
  offset?: number
  count?: number              // max 100
  extended?: boolean
  fields?: string[]
}
output: {
  items: Array<{
    id: number
    fromId: number
    date: number
    text: string
    attachments: unknown[]
    comments: { count: number; canPost: boolean }
    likes: { count: number; userLikes: boolean }
    reposts: { count: number; userReposted: boolean }
    isPinned: boolean
    signerId?: number
  }>
  total: number
  hasMore: boolean
}

Comments

`vk_comments_list`


Token	C+U
Destructive	✗
Card	`generic`

args: {
  ownerId: number           // group id (negative)
  postId: number
  sort?: 'asc'|'desc'
  offset?: number
  count?: number            // max 100
  previewLength?: number    // default 0 = full text
  extended?: boolean
}
output: {
  items: Array<{
    id: number
    fromId: number
    date: number
    text: string
    likes: { count: number }
    thread?: { count: number; items: unknown[] }
    attachments?: unknown[]
  }>
  realOffset: number
  total: number
  hasMore: boolean
}

`vk_comment_manage`


Token	C (admin)
Destructive	⚠⚠
Card	`generic`

args: {
  ownerId: number
  commentIds: number[]
  action: 'delete'|'restore'|'reportSpam'
}
output: { results: Array<{ commentId: number; ok: boolean; error?: string }> }

Pre-execute gate forces ask for delete.

Media

`vk_media_upload`


Token	C
Destructive	⚠ (creates an object)
Card	`generic`

args: {
  type: 'photo_wall'|'photo_message'|'doc'|'video'|'story'
  source: { kind: 'file'; path: string } | { kind: 'url'; url: string }
  // type-specific options:
  caption?: string          // photo/story
  isBoard?: boolean         // photo: upload to board topic
  title?: string            // doc, video
  tags?: string             // doc
  description?: string      // video
  albumId?: number          // photo into album
  wallId?: number           // photo for a specific wall post
}
output: {
  attachment: string        // e.g. "photo-123_456"
  type: string
  ownerId: number
  id: number
  url?: string              // access URL for video (not yet processed)
}

Uses ctx.jobs when the file is large enough that upload > timeoutMs.

Board

`vk_board_topic`


Token	C
Destructive	⚠
Card	`generic`

args: {
  action: 'create'|'close'|'open'|'fix'|'unfix'|'delete'
  topicId?: number          // required for all actions except 'create'
  title?: string            // required for 'create'
  text?: string             // required for 'create' — opening message
  fromGroup?: boolean
}
output: { topicId: number; ok: boolean; error?: string }

`vk_board_comment`


Token	C
Destructive	⚠
Card	`generic`

args: {
  topicId: number
  action: 'create'|'delete'
  text?: string            // required for 'create'
  attachments?: string[]
  fromGroup?: boolean
  commentId?: number       // required for 'delete'
}
output: { commentId: number; ok: boolean; error?: string }

Market

`vk_market_manage`


Token	C
Destructive	⚠
Card	`generic`

args: {
  action: 'add'|'edit'|'delete'|'restore'
  productId?: number       // required for edit/delete/restore
  name?: string            // required for add/edit
  description?: string
  price: number
  oldPrice?: number
  categoryId?: number
  mainPhotoId?: number     // photo id from vk_media_upload
  photoIds?: number[]
  url?: string
  availability?: 0|1|2     // 0 available, 1 removed, 2 inactive
}
output: { productId: number; ok: boolean; error?: string }

Messages

`vk_messages_send`


Token	C
Destructive	⚠
Card	`generic`

args: {
  peerId: number           // user id, or chat id (2000000000 + id), or group id (negative)
  message: string
  attachments?: string[]
  keyboard?: unknown       // JSON keyboard object
  forward?: { peerId: number; conversationMessageIds: number[] }
  replyTo?: number         // conversation_message_id
  randomId?: number        // plugin generates if absent (idempotency)
  lat?: number
  long?: number
  dontParseLinks?: boolean
  disableMentions?: boolean
}
output: { messageId: number; conversationMessageId: number; peerId: number; error?: string }

`vk_messages_list`


Token	C
Destructive	✗
Card	`generic`

args: {
  filter?: 'all'|'unread'|'important'
  offset?: number
  count?: number           // max 200
  extended?: boolean
  fields?: string[]
}
output: {
  items: Array<{
    peer: { id: number; type: string; localId?: number; title?: string }
    conversation: { inRead: number; outRead: number; unreadCount: number; canWrite: boolean; lastMessageId: number }
  }>
  total: number
  hasMore: boolean
}

Analytics

`vk_stats_get`


Token	U
Destructive	✗
Card	`generic`

args: {
  dateFrom: string         // YYYY-MM-DD
  dateTo: string
  interval?: 'day'|'week'|'month'|'hour'   // default 'day'
  filters?: Array<'visitors'|'reach'|'activity'|'demography'|'subscriptions'>
}
output: Array<{
  period: { from: string; to: string }
  visitors: number
  reach: number
  reachSubscribers: number
  activity: { likes: number; comments: number; subscribed: number; unsubscribed: number; hides: number; reports: number }
}>

`vk_shortlink`


Token	C
Destructive	✗
Card	`generic`

args: { url: string; privateKey?: boolean }
output: { key: string; shortUrl: string; url: string; viewCount: number }

Infrastructure

`vk_callback_manage`


Token	C (admin)
Destructive	⚠
Card	`generic`

args: {
  action: 'list'|'add'|'edit'|'delete'|'getSettings'|'setSettings'|'getConfirmationCode'
  serverId?: number        // for edit/delete
  url?: string             // for add/edit
  title?: string           // for add/edit
  secret?: string          // for add/edit
  settings?: Record<string, boolean>  // for setSettings
}
output: unknown           // shape depends on action — documented in render

`vk_longpoll_control`


Token	C
Destructive	⚠
Card	`generic`

args: { action: 'start'|'stop'|'status' }
output: {
  running: boolean
  jobId?: string
  lastEventTs?: number
  eventsReceived: number
  errors: number
}

`vk_moderation_rules`


Token	C
Destructive	⚠
Card	`generic`

args: { action: 'list'|'add'|'remove'|'update' }
// 'add':
//   rule: { id, match: { type: 'keyword'|'regex'|'newMember'|'link'|'externalLink' }, pattern?, action: { kind: 'ban'|'delete'|'warn'|'notify' }, durationH?, reason? }
// 'remove':
//   ruleId: string
// 'update':
//   rule: { id, ... }
output: { rules: Array<Rule>; ok: boolean; error?: string }

`vk_api_raw`


Token	C or U (whichever is configured)
Destructive	⚠⚠
Card	`generic`

args: { method: string; params: Record<string, unknown> }
output: { response: unknown; method: string; audited: boolean }

Disabled unless safety.rawApiEnabled is true. Restricted to an allowlist of method prefixes. Every call is audit-logged regardless of success. Pre-execute gate forces ask.

Tools Reference

Community

vk_community_info

vk_community_update

Members

vk_members_list

vk_members_manage

vk_member_status

Moderation

vk_ban_list

vk_ban_manage

vk_requests_list

vk_requests_handle

Managers

vk_managers_list

vk_manager_set

Wall

vk_wall_post

vk_wall_edit

vk_wall_delete

vk_wall_pin

vk_wall_list

Comments

vk_comments_list

vk_comment_manage

Media

vk_media_upload

Board

vk_board_topic

vk_board_comment

Market

vk_market_manage

Messages

vk_messages_send

vk_messages_list

Analytics

vk_stats_get

vk_shortlink

Infrastructure

vk_callback_manage

vk_longpoll_control

vk_moderation_rules

vk_api_raw

dsh-vk-group

Overview

Platform reference

Operating

Building

Reference

`vk_community_info`

`vk_community_update`

`vk_members_list`

`vk_members_manage`

`vk_member_status`

`vk_ban_list`

`vk_ban_manage`

`vk_requests_list`

`vk_requests_handle`

`vk_managers_list`

`vk_manager_set`

`vk_wall_post`

`vk_wall_edit`

`vk_wall_delete`

`vk_wall_pin`

`vk_wall_list`

`vk_comments_list`

`vk_comment_manage`

`vk_media_upload`

`vk_board_topic`

`vk_board_comment`

`vk_market_manage`

`vk_messages_send`

`vk_messages_list`

`vk_stats_get`

`vk_shortlink`

`vk_callback_manage`

`vk_longpoll_control`

`vk_moderation_rules`

`vk_api_raw`