list_chatsFetch the current user's chats with pagination and filters by unread status, text messages, vacancy status, or specific vacancy IDs.
List chats of the current user (applicant or employer) with pagination and filters: unread only, with text messages, by vacancy status or explicit vacancy ids.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| per_page | No | ||
| filter_unread | No | ||
| vacancy_status | No | ||
| filter_has_text_message | No | ||
| filter_with_vacancy_ids | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden; it does disclose that results are implicitly read-only and scoped to the authenticated user's role, which is useful authorization context. However, it says nothing about ordering, whether the list is complete or capped, or what happens with no filters, so meaningful behavioral gaps remain for a no-annotation tool.
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 dense sentence with the resource, scope, and filter enumeration front-loaded and no filler. It is slightly compressed—the filter list runs together in a way that requires a second read—but nothing is redundant.
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?
With no output schema, no annotations, and six parameters at 0% schema coverage, the description needs to do more heavy lifting than it does: pagination defaults and the vacancy-ids string format are unresolved. It is adequate to recognize the tool and start a call, but not complete for correct invocation across all filters.
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 explain the intent of four of six parameters (unread only, with text messages, by vacancy status, explicit vacancy ids). It leaves page and per_page completely unexplained and gives no format guidance for filter_with_vacancy_ids, which is typed only as a bare string, so the compensation is partial.
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?
States a specific verb and resource ("List chats") plus the scope ("of the current user (applicant or employer)") and the available filters, so an agent knows exactly what this returns. It does not name or distinguish itself from the closest sibling, list_negotiations, which also lists conversation-like objects, so it falls short of a 5.
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 description implies usage through the "current user (applicant or employer)" scope but never says when to pick this over list_negotiations, get_unread_counters, or list_chat_messages. There are no exclusions, prerequisites, or alternative-routing hints, leaving the agent to infer selection from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.