Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Twenty CRM MCP search for companies with 'Acme' in the name"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give Codex, Claude Code, and other MCP clients controlled access to your Twenty CRM.
This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or sponsored by Twenty.com, PBC.
Twenty exposes the same operation families across many object types. This
server uses a validated entity parameter, so an agent loads 14 composable
tools instead of hundreds of near-duplicate tool definitions.
Read, search, create, update, group, deduplicate, merge, restore, and batch records.
Covers 28 standard Twenty objects, including companies, people, opportunities, tasks, notes, workflows, calendar objects, and messaging objects.
Runs locally over stdio. Your API key is sent only to the Twenty API.
Uses conservative defaults: no hard delete, guarded soft delete and merge, and a restricted write allowlist.
Returns structured MCP content for reliable follow-up tool calls.
Related MCP server: CRM MCP Server
Twenty 2.0 introduced native MCP capabilities. If your workspace already provides the access and controls you need, start with the native integration.
This project is useful when you want a small, auditable local stdio process, API-key authentication, compatibility with a self-hosted or older workspace, or explicit safety controls in front of record writes. Its differentiator is a stable 14-tool surface with a write allowlist, dry-run merges, and no hard delete—not replacing every native Twenty feature.
Node.js 20.6 or newer
Codex, Claude Code, or another stdio-compatible MCP client
A Twenty workspace and API key
git clone https://github.com/0xfabrica/twentycrm-mcp.git
cd twentycrm-mcp
npm ci
npm testCreate a local environment file:
cp .env.example .envEdit .env:
# Twenty Cloud
TWENTY_API_URL=https://api.twenty.com/rest
# Create this in Settings > API & Webhooks
TWENTY_API_KEY=replace_with_your_api_key
# Keep destructive operations disabled for normal agent sessions
TWENTY_ALLOW_DESTRUCTIVE=falseThis example omits TWENTY_WRITABLE_ENTITIES, so the server uses its default
CRM write allowlist: companies, people, opportunities, tasks, notes, note
targets, and task targets. To start in fully read-only mode, add:
TWENTY_WRITABLE_ENTITIES=
TWENTY_ALLOW_DESTRUCTIVE=falseAn empty TWENTY_WRITABLE_ENTITIES value disables every write tool. By
contrast, TWENTY_ALLOW_DESTRUCTIVE=false only blocks soft deletes and real
merges; it does not block ordinary creates, updates, upserts, or restores.
For a self-hosted workspace, use https://your-domain.example/rest. The URL
must end in /rest, not /rest/core.
Create the key in Settings > API & Webhooks > Create key. Twenty shows it once, so store it immediately. Assign the key a least-privilege role whenever possible. See the official Twenty API documentation.
The .env file is ignored by Git. On macOS or Linux, you can additionally
restrict it to your user:
chmod 600 .envBoth commands below store absolute paths, so run them from the cloned repo.
codex mcp add twenty-crm -- node \
--env-file="$(pwd)/.env" \
"$(pwd)/dist/index.js"Inspect the registration:
codex mcp get twenty-crmFor manual configuration, add this to ~/.codex/config.toml and replace both
paths:
[mcp_servers.twenty-crm]
command = "node"
args = [
"--env-file=/absolute/path/to/twentycrm-mcp/.env",
"/absolute/path/to/twentycrm-mcp/dist/index.js"
]
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"claude mcp add --scope user twenty-crm -- node \
--env-file="$(pwd)/.env" \
"$(pwd)/dist/index.js"Inspect the registration:
claude mcp get twenty-crmRestart the MCP client after registering the server.
From the cloned repository:
$Repo = (Get-Location).Path
Copy-Item .env.example .env
# Edit .env and replace the example API key before continuing.
codex mcp add twenty-crm -- node "--env-file=$Repo\.env" "$Repo\dist\index.js"
claude mcp add --scope user twenty-crm -- node "--env-file=$Repo\.env" "$Repo\dist\index.js"Then restart Codex or Claude Code and inspect the registration with the same
mcp get commands shown above. Codex's manual user configuration is at
$env:USERPROFILE\.codex\config.toml.
Do not keep .env in a shared or cloud-synced folder. If you prefer persistent
user environment variables on Windows, set them from PowerShell and restart
the client:
[Environment]::SetEnvironmentVariable("TWENTY_API_URL", "https://api.twenty.com/rest", "User")
[Environment]::SetEnvironmentVariable("TWENTY_API_KEY", "your-api-key", "User")If you prefer not to use a local .env, export the variables in the parent
environment before launching your MCP client:
export TWENTY_API_URL="https://api.twenty.com/rest"
export TWENTY_API_KEY="your-api-key"Then register node /absolute/path/to/twentycrm-mcp/dist/index.js without the
--env-file argument. Do not place a real key directly in MCP JSON or TOML.
Start with discovery and keep writes explicit:
List the 10 most recently updated companies in Twenty. Do not modify anything.Find people whose email domain is example.com and summarize their companies.Preview possible duplicate companies named Acme. Do not merge records.Create a follow-up task for this opportunity, then show me the created record.Tool | Behavior |
| List, filter, order, and page through an object |
| Targeted list with a required filter |
| Fetch one record by UUID |
| Create or optionally upsert one record |
| Patch one record |
| Guarded soft delete |
| Create 1–50 records |
| Patch records matching a required filter |
| Guarded filtered soft delete |
| Check IDs or candidate data for duplicates |
| Group and aggregate records |
| Preview a merge or perform a guarded merge |
| Restore one soft-deleted record |
| Restore records matching a filter |
Agents can make mistakes. This server limits the blast radius, but it is not an authorization boundary.
There is no hard-delete tool.
Delete operations always request Twenty's soft-delete behavior.
Soft delete and real merges are disabled unless
TWENTY_ALLOW_DESTRUCTIVE=true.
Merge defaults to dry_run=true.
Batch creates are limited to 50 records per call.
Non-local API URLs must use HTTPS.
API errors do not echo response bodies or credentials.
Tool annotations tell clients which operations are read-only or destructive.
Use a least-privilege Twenty role, review tool calls before approval, and keep backups appropriate for your workspace.
TWENTY_WRITABLE_ENTITIES: choose what agents may modifyThis is a server-side write allowlist. It controls which supported Twenty objects the MCP may create, update, restore, soft-delete, or merge.
If the variable is omitted, writes are allowed by default only for:
companies,people,opportunities,tasks,notes,noteTargets,taskTargetsSet a narrower comma-separated list to reduce write access:
TWENTY_WRITABLE_ENTITIES=companies,people,opportunities,tasks,notesSet an explicitly empty value for read-only mode:
TWENTY_WRITABLE_ENTITIES=Objects outside the allowlist remain readable but cannot be modified through this MCP. The allowlist can only reduce access: the role assigned to the Twenty API key must also permit the operation. Keep internal and system objects read-only unless you have reviewed their schema and permissions.
Changes take effect when the MCP process starts. Restart Codex, Claude Code, or
your other MCP client after editing .env.
TWENTY_ALLOW_DESTRUCTIVE: guard deletes and mergesKeep this setting false or unset during routine use:
TWENTY_ALLOW_DESTRUCTIVE=falseWith false:
twenty_soft_delete_record and twenty_batch_soft_delete_records are
blocked before an HTTP request is sent.
twenty_merge_records may preview a merge with dry_run=true, but cannot
perform the real merge.
Ordinary creates, upserts, updates, batch writes, and restores are still
allowed for objects in TWENTY_WRITABLE_ENTITIES.
Set it to true only for a deliberate, supervised session. The write allowlist
and Twenty API-key permissions still apply. This server never exposes a hard
delete, even when destructive operations are enabled.
After the supervised operation, set it back to false and restart the MCP
client.
Preset | Configuration | Result |
Read-only first run |
| All reads work; every write is blocked |
Standard CRM work | Omit | Common CRM objects can be created or updated; deletes and real merges are blocked |
Narrow writer | Set only the required entities; keep destructive | Writes are limited to those objects |
Supervised cleanup | Set only required entities and temporarily set destructive | Soft delete and real merge become available for those objects |
TWENTY_ALLOW_DESTRUCTIVE=false does not make the entire server read-only.
It blocks soft deletes and real merges; the configured write allowlist still
permits ordinary record writes.
Category | Tools | Behavior |
Read-only | list, search, get, find duplicates, group | Never modifies records |
Writes | create/upsert, update, batch create/update, restore | Modifies allowed objects without the destructive flag |
Guarded | soft delete, batch soft delete | Requires |
Preview/guarded | merge | Dry-run by default; a real merge requires the destructive flag |
An upsert may update an existing record when Twenty finds a matching unique value. Review the proposed data and use a least-privilege API-key role even when destructive operations are disabled.
Variable | Required | Default | Purpose |
| Yes | — | Twenty REST root ending in |
| Yes | — | Workspace API key |
| No | Common CRM objects when omitted | Comma-separated write allowlist; an empty value disables all writes |
| No |
| Enables soft delete and non-dry-run merge; does not control ordinary writes |
| No |
| Allows HTTP for non-local testing; not recommended |
The current allowlist contains 28 standard objects:
companies
people
opportunities
tasks
notes
attachments
timelineActivities
dashboards
workflows
workflowVersions
workflowRuns
workflowAutomatedTriggers
calendarEvents
calendarChannels
calendarEventParticipants
calendarChannelEventAssociations
messages
messageChannels
messageThreads
messageParticipants
messageChannelMessageAssociations
messageFolders
messageChannelMessageAssociationMessageFolders
noteTargets
taskTargets
connectedAccounts
blocklists
workspaceMembersTwenty generates APIs from each workspace schema. Custom objects are not yet accepted by this server's validated entity allowlist; contributions that add a safe discovery mechanism are welcome.
Build the TypeScript server:
npm run buildRun the offline protocol and API-contract smoke test:
npm testRun the optional live, read-only smoke test after setting credentials:
npm run test:liveThe live test lists at most one company and does not modify CRM data.
Unlike codex mcp get and claude mcp get, which inspect client registration,
this command verifies authenticated access to the Twenty API.
CI runs the build, offline smoke test, and a production-dependency audit on every pull request.
TWENTY_API_KEY and TWENTY_API_URL are requiredThe MCP process cannot see your credentials. Use an absolute .env path in the
client configuration or launch the client from a shell that exports both
variables.
getaddrinfo ENOTFOUND your-twenty.example.comThe example URL was not replaced. Twenty Cloud uses
https://api.twenty.com/rest; self-hosted installations use their own domain.
401 or 403Replace or rotate the API key, then check the role assigned to that key in Twenty. A valid key can still be denied access to specific objects or writes.
404Check that the base URL ends in /rest, the entity exists in your workspace,
and the record UUID is correct.
Run npm run build, confirm the configured dist/index.js path is absolute,
and restart the client. Use codex mcp get twenty-crm or
claude mcp get twenty-crm to inspect the registration.
This server targets Twenty's core REST record API, not its metadata API.
It does not send email. Use an approved Twenty workflow, n8n workflow, or mail integration for delivery.
Workspace-specific custom objects are not currently auto-discovered.
Twenty's native MCP may be a better fit for current cloud workspaces.
Twenty's API and object schemas may change; deploy a reviewed commit or release tag and test it before using sensitive workflows.
Never commit a Twenty API key. If a key appears in a commit, issue, CI log, or terminal transcript, rotate it immediately. See SECURITY.md for the vulnerability-reporting process.
Issues and pull requests are welcome. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md before proposing a change.
This project is available under the MIT License.
Twenty is a product and name of Twenty.com, PBC. This independent project uses the name only to identify API compatibility. See NOTICE.md.
Create 1-50 records in an allowed business object.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior. Description adds little beyond the schema: mentions batch size (1-50) but fails to disclose idempotency, atomicity, or error handling. Adequate but minimal.
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?
Single 7-word sentence is highly concise. However, it omits helpful structuring like usage tips or important constraints. Efficient but could be slightly more structured.
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?
No output schema, so description should explain return value, especially for a batch operation. It also lacks coverage of error scenarios, partial failures, or idempotency. Given complexity of batch create, description is incomplete.
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?
All three parameters have descriptions in the schema (100% coverage). The description itself adds no extra meaning; it only restates the batch limit. Baseline 3 is appropriate.
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?
Description clearly states the verb 'create', resource 'records', and scope '1-50 in an allowed business object'. This distinguishes it from sibling tools like batch update or delete.
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?
No guidance on when to use this tool vs alternatives. It does not mention that for single records one should use twenty_create_record, nor does it address batch size limits beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete records matching a required filter. Never hard-deletes. Disabled unless TWENTY_ALLOW_DESTRUCTIVE=true.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | Yes | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), description clarifies it's a soft-delete, never hard-deletes, and requires an env variable. No contradiction.
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?
Two sentences, no fluff. Front-loaded with purpose and key behavior. Every sentence earns its place.
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?
Lacks output schema info, but core behavior is fully covered. No mention of restore alternative among siblings, but adequate for a batch soft-delete tool.
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 coverage is 100% (baseline 3). Description adds value: for entity, suggests preferred objects; for filter, provides an example; for response_format, explains JSON vs markdown use cases.
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?
Description clearly states verb 'soft-delete' on 'records', and adds the critical constraint 'Never hard-deletes'. Distinguishes from sibling tools like hard-delete operations.
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?
Explicitly mentions the prerequisite TWENTY_ALLOW_DESTRUCTIVE=true, implying when it's usable. Lacks explicit comparison to the singular soft_delete_record sibling, but context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch all records matching a required filter in an allowed business object.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Record fields. Use field names from your Twenty workspace schema. | |
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | Yes | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true, providing safety profile. The description adds no further behavioral context beyond 'Patch all records matching a filter'. It does not disclose potential side effects (e.g., irreversible changes) or behavior with large result sets. With annotations present, the description adds marginal value.
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?
The description is a single, compact sentence with no wasted words. It front-loads the core purpose and is immediately understandable.
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?
Given the tool's complexity (5 params, 3 required, no output schema), the description covers the essential behavior: it patches all matching records. The missing output format details are compensated by the 'response_format' parameter description. Annotations fill safety gaps. Slight lack of detail on error handling or partial updates, but adequate overall.
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 coverage is 100%, but the description adds meaningful guidance: filter syntax example ('name[ilike]:...'), entity preference note, and output format recommendation. This enhances understanding beyond the schema's basic definitions, warranting above baseline.
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 title 'Batch-update Twenty CRM records' and description 'Patch all records matching a required filter in an allowed business object' clearly state the action (patch), resource (records in business object), and scope (all matching a filter). This distinguishes it from siblings like twenty_update_record (single record) and twenty_batch_create_records (create vs update).
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 when to use: when you need to update multiple records based on a filter. It contrasts with single-record update and batch create/delete via sibling context, but it does not explicitly state when not to use or recommend alternatives. The guidance is clear but lacks exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create one record in an allowed business object. Internal/system objects are read-only by default.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Record fields. Use field names from your Twenty workspace schema. | |
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| upsert | No | ||
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior, but the description adds context that internal objects are read-only, which is a behavioral constraint. It is consistent with annotations and provides extra clarity without contradiction.
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?
The description is a single sentence that is concise and front-loaded with the core purpose. It could benefit from a bit more structure, but it is efficient and to the point.
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 has 5 parameters and no output schema, yet the description does not mention return values, error handling, or side effects. For a creation tool, missing details on what the response contains (e.g., the created record ID) makes it incomplete.
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 covers 80% of parameters with descriptions. The description does not add any additional meaning beyond what is in the schema. Baseline 3 is appropriate as the schema already handles parameter documentation adequately.
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 clearly states the action ('Create') and resource ('one record in an allowed business object'), and implicitly distinguishes from batch or update tools. It also notes that internal/system objects are read-only, which helps differentiate permissible targets.
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 mentions that internal/system objects are read-only, giving a when-not-to-use hint. However, it does not explicitly guide when to use this tool versus siblings like twenty_batch_create_records or twenty_update_record. The schema provides preferences for normal CRM objects, but the description itself lacks explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check supplied record IDs or candidate data for duplicates without modifying CRM data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds 'without modifying CRM data' which is redundant and does not clarify behavior like what happens if duplicates are found (return type, format, pagination). No new insights beyond annotations.
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?
The description is short (one sentence), which is generally good, but it lacks essential details that could be added without becoming verbose. It is not optimally structured for agent comprehension.
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?
Given no output schema, no parameters, and a description that implies inputs, the tool definition is critically incomplete. There is no way for an AI agent to know how to invoke this tool correctly (e.g., what to pass, what to expect). Other sibling tools have richer descriptions.
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?
Input schema has zero parameters, yet the description mentions 'supplied record IDs or candidate data'. This is a direct contradiction. The description does not add meaning; it misleads about required inputs. Schema coverage is 100% (trivially) but description compensates negatively.
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 states the tool finds duplicates and is read-only, but it doesn't specify what constitutes duplicates (exact IDs vs fuzzy matching) or the scope (within a specific object type?). It moderately distinguishes from siblings like 'twenty_search_records' but not clearly.
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?
No guidance on when to use this tool versus other record tools (e.g., list, search, merge). The description says 'check supplied record IDs or candidate data' but the input schema has no parameters, creating confusion about how to supply data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one record by object name and UUID. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds 'Read-only' which is consistent, but does not provide additional behavioral context beyond what annotations already convey. No contradiction.
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?
The description is a single, clear sentence without any unnecessary words. It is front-loaded with the key action and immediately follows with the read-only qualifier. No fluff.
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?
Although the tool is simple, the description omits details about return format, error handling, and parameter nuances (e.g., depth, response_format). No output schema is provided, so the description should at least mention what the agent can expect as output. The openness of the tool (openWorldHint) also suggests more context about potential side effects or data freshness would be helpful.
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 coverage is 75%, so the input schema documents most parameters. The description does not add any parameter-specific meaning or context beyond what the schema already provides. Baseline of 3 is appropriate given the high schema coverage.
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 clearly states 'Fetch one record by object name and UUID' and includes 'Read-only', which distinguishes it from write siblings like twenty_create_record or twenty_update_record. The verb 'fetch' and resource 'record' are specific, but it could be more explicit about when to use this tool versus twenty_list_records or twenty_search_records.
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?
No usage guidelines provided. The description does not indicate when to use this tool over alternatives such as twenty_list_records or twenty_search_records. It only describes the operation without context about when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Group and optionally aggregate records using Twenty group_by syntax. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | No | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| group_by | Yes | Twenty group_by expression, such as ["stage"] or ["createdAt(DAY)"]. | |
| aggregate | No | Optional aggregate expression supported by Twenty, such as ["id(COUNT)"]. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
| include_records_sample | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds 'Read-only' which is redundant but confirms safety. It also mentions group_by syntax and optional aggregation, adding some behavioral context beyond annotations.
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?
The description is a single concise sentence that front-loads the purpose. It could be slightly more informative (e.g., mentioning alternatives) but is not verbose.
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 tool with 7 parameters (2 required) and no output schema, the description is very minimal. It lacks examples, syntax details, and guidance on usage patterns, which is inadequate for a complex grouping/aggregation tool.
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 coverage is 71% (5 of 7 parameters described). The description itself does not add parameter-specific details beyond what the schema provides, meeting the baseline for coverage.
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 clearly states the verb (Group and optionally aggregate), the resource (records), and the syntax (group_by syntax). It distinguishes from sibling tools like twenty_list_records by specifying grouping and aggregation capabilities.
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 read-only usage but does not explicitly compare with sibling tools or advise when to use this over a simple listing. More guidance would improve decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List records from any supported Twenty object with filters, ordering, relation depth, and cursor pagination. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| limit | No | ||
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | No | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| order_by | No | ||
| ending_before | No | ||
| starting_after | No | ||
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral details about filters, ordering, depth, and pagination, but these are limited and partially redundant with annotations. No contradictions, but the additional context is moderate.
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?
Single sentence of 13 words, front-loaded with the core action and followed by key capabilities. No filler or redundant content. Efficiently communicates the tool's essence.
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?
Given 8 parameters, no output schema, and moderate annotations, the description covers the basic purpose but omits details like pagination parameters (ending_before, starting_after), response_format options, and return structure. Leaves several aspects unexplained, leaving gaps for an agent.
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 50%, leaving half of parameters without schema descriptions. The description mentions 'filters, ordering, relation depth, and cursor pagination' which loosely cover filter, order_by, depth, and pagination parameters, but does not provide explicit semantics or details for individual parameters. Baseline is 3 given moderate coverage.
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 clearly states the action 'List records' and the resource 'any supported Twenty object', with specific features like filters, ordering, relation depth, and cursor pagination. It distinguishes from mutation siblings by noting it's read-only, but does not explicitly differentiate from twenty_search_records which may also list/search, preventing a top score.
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?
No guidance on when to use this tool versus alternatives like twenty_search_records. Does not specify use cases, prerequisites, or when not to use it. The description lacks explicit context for choosing this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview a merge by default. An actual merge requires dry_run=false and TWENTY_ALLOW_DESTRUCTIVE=true.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true; the description adds that TWENTY_ALLOW_DESTRUCTIVE must be set for actual merge, providing critical behavioral context beyond annotations. No contradiction.
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?
Two sentences, no wasted words. Every sentence earns its place by conveying default behavior and required conditions.
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 description is minimal given the destructive and complex nature. It lacks details on what merging entails, impact on records, preview behavior, and return values. Annotations provide some context, but more completeness would be beneficial.
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 input schema is empty, so description must compensate. It effectively specifies required implicit parameters (dry_run, TWENTY_ALLOW_DESTRUCTIVE) that are not in the schema, adding essential meaning for invoking the tool correctly.
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 clearly states that the tool previews or merges records, with a default preview mode. It distinguishes itself from sibling tools like create/update by specifying the merge action, but does not explicitly differentiate from 'twenty_find_duplicates' which may be related.
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 provides clear guidance: preview by default, actual merge requires dry_run=false and TWENTY_ALLOW_DESTRUCTIVE=true. It does not specify when not to use or list alternatives, but the context is sufficient for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore one soft-deleted record by object and UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds no additional behavioral context such as cascading effects, authorization needs, or record state requirements beyond what annotations provide.
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?
Extremely concise: one sentence of 9 words. No wasted content, front-loaded with the key action and constraints.
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 simple restore operation with idempotent and non-destructive annotations, the description is nearly complete. Lacks mention that the record must be soft-deleted, but overall sufficient for the low complexity.
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 75% (3 of 4 params described). The description barely adds meaning beyond the schema, only reiterating 'by object and UUID'. No additional detail for depth or response_format.
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 clearly states the verb 'restore', resource 'record', and distinguishes it as restoring a single soft-deleted record by object and UUID, differentiating it from the sibling tool twenty_restore_records which handles batch restores.
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?
No explicit guidance on when to use vs alternatives. The description implies usage for single record restoration, but does not mention scenarios like batch restore or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore soft-deleted records matching a required filter.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | Yes | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety: not read-only, not destructive, idempotent, open world. The description adds no extra behavioral context beyond 'restore soft-deleted records'. No contradictions.
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?
Single sentence with no wasted words. It is front-loaded and efficient, though the extreme brevity slightly detracts from completeness.
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 batch operation with 4 parameters and no output schema, the description lacks return value info, error behavior, or side effects. The filter mechanism and depth parameter are schema-documented but the description does not tie them together.
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 coverage is 100% with descriptions for all 4 parameters. The tool description adds no parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.
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 clearly states the verb 'Restore', the resource 'soft-deleted records', and the mechanism 'matching a required filter'. It distinguishes from siblings like the singular 'restore_record' and the opposite 'batch_soft_delete_records'.
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 for restoring soft-deleted records with a filter but provides no explicit guidance on when to use this batch variant over the singular 'restore_record' or other siblings. No when-not-to-use or alternative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a targeted, read-only search using Twenty filter syntax. Prefer this over list when criteria are known.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| limit | No | ||
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| filter | Yes | Twenty filter, for example name[ilike]:"%acme%" or createdAt[gte]:"2026-01-01". | |
| order_by | No | ||
| ending_before | No | ||
| starting_after | No | ||
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. Description adds 'targeted search' and 'filter syntax' but does not elaborate on other behaviors (e.g., pagination, response format). Adequate given annotation coverage.
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?
Two concise sentences with no wasted words. Front-loaded with action and usage guidance.
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?
No output schema exists, so description could explain return format or pagination. It only mentions 'search' and filter syntax. With 8 parameters and a complex filter, more context (e.g., result set handling) would improve completeness.
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 has 50% description coverage (4 of 8 params described). Description does not add parameter-specific details beyond the schema. Baseline of 3 is appropriate as schema provides some information but description fails to compensate for missing param descriptions.
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?
Clearly states it's a read-only search using Twenty filter syntax. Explicitly distinguishes from 'list' by preferring search when criteria are known.
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?
Provides a clear usage preference over list when criteria are known. Lacks explicit when-not or alternative tools beyond list, but the guidance is useful and direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete one record. Never hard-deletes. Disabled unless TWENTY_ALLOW_DESTRUCTIVE=true.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context: it never hard-deletes and is disabled without an environment variable. This provides behavioral transparency beyond annotations.
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?
The description consists of two short sentences, front-loaded with the core purpose, followed by the key condition. Every word is necessary and no redundancy.
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 simple soft-delete operation with 3 parameters and no output schema, the description adequately covers the function, safety guarantee, and activation requirement. It could mention response format or error handling, but is reasonably complete.
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 description does not mention any parameter details. While schema coverage is 67% (entity and response_format have descriptions), the description adds no additional meaning for parameters like id, which lacks schema description.
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 clearly states the verb 'soft-delete' and the resource 'one record'. It explicitly distinguishes from hard-delete and mentions the enabling condition. This differentiates it from sibling tools like batch delete or restore.
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 provides clear guidance on when to use (soft-delete) and when not (hard-delete), and mentions the required environment variable. However, it does not explicitly compare to sibling tools like batch delete or restore, which are present in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch one record in an allowed business object by UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| data | Yes | Record fields. Use field names from your Twenty workspace schema. | |
| depth | No | Relation depth: 0 for the record only, 1 for direct relations. | |
| entity | Yes | Twenty object name. Prefer companies, people, opportunities, tasks, and notes for normal CRM work. | |
| response_format | No | Output format. JSON is best for follow-up tool calls; markdown is easier to read. | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description does not need to repeat these. The description aligns with annotations by stating 'patch', which is a write operation. However, it adds no extra behavioral context such as error handling or what happens on missing records, which would be helpful given the destructive hint.
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?
The description is a single, efficient sentence that conveys the core purpose without any extraneous words. It is perfectly concise and 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?
Given that there is no output schema and the tool has moderate complexity (5 params, nested objects), the description could mention what the response contains (e.g., updated record or success confirmation). It adequately covers the action but leaves the return value unspecified.
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 high (80%), with clear descriptions for most parameters (id, entity, depth, response_format). The description adds no parameter-specific details beyond what is in the schema, so its contribution is neutral. Baseline of 3 is appropriate.
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 clearly states 'Patch one record' with the verb 'patch' and resource 'one record', scoped by 'allowed business object' and 'UUID'. This distinguishes it from sibling tools like batch create/update and soft delete, making the tool's purpose unambiguous.
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 provides no guidance on when to use this tool versus alternatives. It does not mention batch operations for multiple records or other update strategies, leaving the agent to infer usage context from the sibling tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1twenty_batch_create_recordstwenty_batch_soft_delete_recordstwenty_batch_update_recordstwenty_create_recordtwenty_find_duplicatestwenty_get_recordtwenty_group_recordstwenty_list_recordstwenty_merge_recordstwenty_restore_recordtwenty_restore_recordstwenty_search_recordstwenty_soft_delete_recordtwenty_update_recordScored across 14 tools
Each tool targets a distinct operation (create, get, list, search, update, soft-delete, restore, merge, group, find duplicates) with no overlap. Batch and single variants are clearly differentiated by name and description.
All tools follow the consistent pattern 'twenty_<action>_<object?>' using snake_case and lowercase, with verbs like create, get, list, update, soft_delete, restore, merge, etc. No mixing of conventions.
14 tools cover the CRM domain comprehensively without being excessive. Each tool serves a distinct purpose, and the count aligns well with a full-featured client.
Covers CRUD, batch operations, soft delete/restore, deduplication, merging, and grouping. Missing hard delete (intentionally omitted) and some advanced operations like export or analytics, but the core lifecycle is complete.
Read people, companies, opportunities, notes and tasks; create and update records in Twenty CRM.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
Build multi-tenant apps over MCP. Schemas, CRUD, deploys — access control enforced server-side.
