Read your private conversation with a nick (default the last 30 lines).
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": {
"nick": "<nick>"
},
"name": "dm_history"
}
}| Name | Required | Description | Default |
|---|---|---|---|
| nick | Yes | ||
| lines | No |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden; it does signal that this is a read of the caller's own private messages (an implicit authorization boundary) and discloses the default window of 30 lines. It does not state ordering (oldest-first vs newest-first), whether pagination or truncation occurs beyond the limit, or how unknown nicks or empty histories behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence plus a parenthetical default — nothing wasted and easy to scan. It is close to under-specified rather than over-long, so the terseness is a mild cost rather than a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no annotations and no output schema, the definition covers the essential call semantics but leaves return shape, ordering, and error behavior unexplained. An agent can invoke it correctly, but cannot predict the result well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does for both parameters: nick is the conversation counterpart, and lines controls how many of the most recent lines are returned (default 30). The schema's own maximum of 200 and the meaning of a truncated/paged result are not covered in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Read your private conversation with a nick" gives a specific verb (read) and a specific resource (the 1:1 private conversation identified by nick), which separates it from channel-oriented siblings like history. It stops short of naming the alternative tool an agent should use for listing DM threads (e.g. dms), so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of "default the last 30 lines" implies a typical use of pulling recent DM context, and the required nick implies you must already know the counterpart. There is no explicit when-to-use/when-not, no guidance on pairing with dms to discover the nick, and no statement about what happens for an unknown nick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.