Get the 1:1 direct-message conversation with a person, creating it if it does not exist yet. Returns the conversation (use its id with send_message). Use list_people to find user_id.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The ID of the person to get the direct-message conversation with. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety hints (all false), so the description carries the burden. It clearly discloses the side effect of creating a conversation if absent and states what it returns. It does not mention error conditions or permission requirements, but for a simple tool this is adequate.
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?
Three short sentences, each with a distinct purpose: main function, return-value usage, and parameter lookup. No filler or redundancy, perfectly front-loaded.
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?
The tool is very simple: one parameter, no output schema. The description covers purpose, behavior, return value usage, and parameter source. There is no meaningful gap for the agent to make a correct call.
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?
The schema already fully documents user_id with a description, giving a baseline of 3. The description adds extra value by telling the agent how to obtain user_id (via list_people), which goes beyond the schema.
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?
The description uses a specific verb+resource ('Get the 1:1 direct-message conversation') and explicitly notes the create-if-missing behavior, making it distinct from sibling tools like get_conversation or list_conversations. The purpose is unambiguous and action-oriented.
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?
It gives clear when-to-use context by explaining the logical flow: first use list_people to find user_id, then call this tool, then use the returned id with send_message. It does not explicitly contrast with alternatives, but the workflow guidance is strong.
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.
Tools are organized into clear namespaced subdomains (twchat, twdesk, twprojects, twspaces) with distinct actions per resource. However, the twprojects domain has many tools for custom items that share repetitive descriptions, and a few tools like `twprojects-search` could overlap with list tools, but overall boundaries are clear.
Naming follows a consistent `{prefix}-{verb}_{noun}` pattern across all tools, with prefixes indicating the subdomain. The only minor inconsistency is the use of singular and plural in nouns (e.g., `get_company` vs `list_companies`) and some verbs like `link_project_to_workflow` vs `move_tasks`, but the pattern is predictable.
With 200 tools, this server is extremely large, covering multiple Teamwork products (Chat, Desk, Projects, Spaces). While each subdomain is well-scoped individually, the sheer number makes it unwieldy for an agent to navigate, and many tools could be pruned or combined (e.g., many custom item variants). It's on the high end of acceptable.
The surface is comprehensive, covering CRUD operations for most entities, specialized queries (search, count, summarize), and cross-entity linking (link_task_to_ticket). Minor gaps include lack of delete tools for most entities and some missing lifecycle operations (e.g., archiving), but core workflows are well-covered.