x-mcp

X Direct Messages

x_dms

Destructive

Send, read, and delete X Direct Messages: message users or existing conversations, list recent DM events, and fetch conversation history by conversation or user.

Instructions

Send and read Direct Messages: send to a user or an existing conversation, read events, read a conversation, and delete an event.

Actions (pass "action" plus that action's parameters):

send: Send a DM to a user, creating the 1:1 conversation if needed. [requires: text]
send_to_conversation: Send a message to an existing DM conversation by conversation id. [requires: conversation_id, text]
events: Recent Direct Message events across all conversations, newest first (1-100 per page).
conversation: Messages in one DM conversation, newest first (1-100 per page). [requires: conversation_id]
with_user: Messages exchanged with one user, newest first (1-100 per page).
delete: Delete a Direct Message event sent by the authenticated account. [requires: event_id]

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "x_dms"
  }
}

Input Schema

Name	Required	Description
`text`	No	Message text.
`action`	Yes	Action to perform. One of: send, send_to_conversation, events, conversation, with_user, delete.
`user_id`	No	Numeric X user id.
`event_id`	No	Numeric DM event id.
`media_id`	No	Optional media id uploaded with category dm_image or dm_video.
`username`	No	X handle without the @ prefix.
`next_token`	No	Cursor from a previous response (meta.next_token).
`event_types`	No	Filter by event type, e.g. MessageCreate, ParticipantsJoin, ParticipantsLeave.
`max_results`	No
`conversation_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Nov 7, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is carried structurally; the description adds that delete is restricted to events sent by the authenticated account, and that send may create a 1:1 conversation as a side effect. It does not mention rate limits or what deletion means for the recipient's copy, but it does not contradict the annotations.

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 one-line summary is front-loaded and the per-action bullet list is easy to scan, with required parameters bracketed inline. It repeats the action enum verbatim from the schema, which is mild redundancy but aids routing.

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

Completeness3/5

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

For a 10-parameter, six-action tool with no output schema, the action-to-parameter contract is the critical missing piece, and it is only partly delivered (with_user has no stated requirements, pagination is undocumented in prose). The description is adequate for the send/delete paths but leaves an agent guessing on the read paths.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 80% schema coverage the schema already documents individual parameters, so the baseline is 3. The description genuinely adds value by mapping parameters to actions (text for send, conversation_id for conversation), but the mapping is incomplete: with_user's required parameters are unspecified, and next_token, event_types and media_id are never tied to the actions that accept them.

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 names the resource (Direct Messages) and enumerates six concrete verbs (send, send_to_conversation, events, conversation, with_user, delete), so an agent immediately knows the tool's scope. It is also distinguishable from siblings like x_posts or x_timelines, which cover different X resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Each action is annotated with the situation that selects it, notably the send vs send_to_conversation distinction and the conversation vs with_user distinction (by conversation id vs by user). It does not explain when to prefer this tool over sibling tools such as x_users for resolving a user id, and the with_user action omits its own '[requires: ...]' note even though user_id/username appear necessary.

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

Deploy Server