MCP server for VTENext CRM: exposes the WebService API as tools for Claude and other MCP-compatible clients.
Node.js 18+
A running VTENext instance (self-hosted or Docker, see ../docker)
Related MCP server: nimble-crm-mcp
cd mcp/vtenext/server
npm install
cp .env.example .envEdit .env:
VTENEXT_URL=http://your-vtenext-instance
VTENEXT_USERNAME=admin
VTENEXT_ACCESS_KEY=your_access_key
READ_ONLY=falseThe access key is in VTENext under Admin → Users → [user] → Access Key.
Set READ_ONLY=true to prevent any write operation on VTENext. When enabled, the tools create_opportunita, update_opportunita and add_nota_opportunita return an error instead of writing data.
This is useful when the server is used by AI bots or automated agents that should only read CRM data. To run a read-only instance alongside a full-access one, pass the variable via the MCP config:
{
"mcpServers": {
"vtenext-bot": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp/vtenext/server/index.js"],
"env": {
"VTENEXT_URL": "http://your-vtenext-instance",
"VTENEXT_USERNAME": "admin",
"VTENEXT_ACCESS_KEY": "your_access_key",
"READ_ONLY": "true"
}
}
}
}Add to .mcp.json in your project root:
{
"mcpServers": {
"vtenext": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp/vtenext/server/index.js"]
}
}
}Tool | Description |
| List opportunities with optional filters (status, search, limit) |
| Get full details of an opportunity by ID |
| Search opportunities by name |
| Create a new opportunity (write, blocked in read-only mode) |
| Update status, amount or notes on an existing opportunity (write, blocked in read-only mode) |
Tool | Description |
| Search contacts by name, email or company |
Tool | Description |
| Add a comment/note to an opportunity (write, blocked in read-only mode) |
| List activities linked to an opportunity |
Tool | Description |
| Show available fields for any VTENext module |
| Run a raw VTQL SELECT query |
VTENext uses the vtiger WebService protocol:
GET /webservice.php?operation=getchallenge → token
MD5(token + accessKey) → hashed key
POST /webservice.php with operation=login (form-encoded) → sessionName
Sessions are cached for 4 minutes (token lifetime is 5 minutes).
# Unit tests (no VTENext required)
npm test
# Integration tests (requires live VTENext at VTENEXT_URL)
npm run test:integrationMIT
Maintained by Castaldo Solutions, enterprise-grade technology built for SMEs.
Why we built an MCP server for a CRM instead of an integration: Connecting VTENext to Claude with MCP.
Aggiunge una nota/commento a un'opportunità
| Name | Required | Description | Default |
|---|---|---|---|
| opportunita_id | Yes | ID dell'opportunità (es. 13x42) | |
| testo | Yes | Testo della nota |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'adds' a note/comment, implying a write/mutation operation, but doesn't disclose any behavioral traits: no information about permissions required, whether the operation is idempotent, rate limits, error conditions, or what happens on success/failure. The description is minimal and lacks essential context for a mutation 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?
The description is a single, efficient sentence in Italian that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple tool and front-loaded with the core action.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after adding the note (e.g., returns success confirmation, the created note ID, or error details), nor does it cover behavioral aspects like permissions or side effects. For a 2-parameter write operation, more context is needed.
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 100%, with both parameters clearly documented in the schema ('opportunita_id' and 'testo'). The description adds no additional parameter semantics beyond what the schema provides—it doesn't explain format examples beyond the schema's 'es. 13x42' or provide context about note length/formatting. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Aggiunge' - adds) and the resource ('una nota/commento a un'opportunità' - a note/comment to an opportunity). It distinguishes from siblings like 'create_opportunita' or 'update_opportunita' by focusing specifically on adding notes. However, it doesn't explicitly differentiate from potential note-related tools that might exist.
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 doesn't mention prerequisites (e.g., needing an existing opportunity), when-not-to-use scenarios, or how it relates to sibling tools like 'update_opportunita' which might also modify opportunity data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crea una nuova opportunità in VTENext
| Name | Required | Description | Default |
|---|---|---|---|
| nome | Yes | Nome dell'opportunità | |
| stato | No | Stato (es. Prospecting, Qualification, Closed Won) | Prospecting |
| importo | No | Valore stimato | |
| data_chiusura | No | Data chiusura prevista (YYYY-MM-DD) | |
| descrizione | No | Note o descrizione |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Crea' implies a write/mutation operation, the description doesn't mention permission requirements, whether this operation is idempotent, what happens on success/failure, or any rate limits. For a creation tool with zero annotation coverage, this leaves significant behavioral gaps.
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 with zero wasted words. It's appropriately sized for a creation tool and gets straight to the point without unnecessary elaboration.
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 creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation (e.g., returns an ID, confirmation message), error conditions, or system constraints. The combination of mutation operation + zero annotations + no output schema requires more comprehensive description than provided.
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 100%, so the schema already documents all 5 parameters thoroughly. The description adds no parameter information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does the heavy lifting for parameter documentation.
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 ('Crea una nuova opportunità') and the target system ('in VTENext'), which is a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'update_opportunita' or explain what distinguishes creating from other opportunity-related 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?
The description provides no guidance on when to use this tool versus alternatives like 'update_opportunita' or 'get_opportunita'. There's no mention of prerequisites, when this operation is appropriate, or what distinguishes it from other opportunity-related tools 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.
Mostra i campi disponibili per un modulo VTENext
| Name | Required | Description | Default |
|---|---|---|---|
| modulo | Yes | Nome del modulo (es. Potentials, Contacts, Activities) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool shows available fields, implying a read-only operation, but doesn't disclose any behavioral traits such as permissions needed, rate limits, error handling, or what the output looks like (e.g., format, structure). For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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 in Italian that directly states the tool's purpose without any fluff or redundancy. It's appropriately sized and front-loaded, with every word contributing to understanding what the tool does, making it highly concise and well-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?
Given the tool's complexity (a single-parameter read operation) and the lack of annotations and output schema, the description is incomplete. It doesn't explain what the output contains (e.g., field names, types, descriptions) or any behavioral aspects like error cases. For a tool that retrieves metadata, more context on the return format would be helpful to compensate for the missing structured data.
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 has 100% description coverage, with the single parameter 'modulo' documented as 'Nome del modulo (es. Potentials, Contacts, Activities)'. The description doesn't add any meaning beyond this, as it doesn't elaborate on parameter usage, constraints, or examples. With high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting.
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 what the tool does: 'Mostra i campi disponibili per un modulo VTENext' (Shows available fields for a VTENext module). It specifies the verb 'mostra' (shows) and the resource 'campi disponibili' (available fields) with the target 'un modulo VTENext' (a VTENext module). However, it doesn't explicitly differentiate from sibling tools like 'query_raw' or 'get_opportunita' that might also retrieve module-related data.
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 doesn't mention prerequisites, context, or exclusions, and with sibling tools like 'query_raw' that might handle similar queries, there's no indication of when this specific tool is preferred. The description is purely functional without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recupera i dettagli completi di un'opportunità tramite ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID dell'opportunità (es. 13x42) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. While 'recupera' (retrieves) implies a read operation, the description doesn't disclose important behavioral traits: whether authentication is required, rate limits, error conditions, what 'dettagli completi' (complete details) includes, or response format. For a read tool with zero annotation coverage, this is inadequate.
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 gets straight to the point: 'Recupera i dettagli completi di un'opportunità tramite ID'. There's no wasted language, and it's appropriately sized for a simple retrieval tool. Every word contributes to understanding the tool's purpose.
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 annotations, no output schema, and multiple sibling tools, the description is incomplete. While the purpose is clear, it doesn't help an agent understand when to choose this tool over 'list_opportunita' or 'search_opportunita', what the response contains, or any behavioral constraints. For a tool in a family of opportunity-related tools, more context is needed.
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 100% (the single parameter 'id' has a description in the schema), so the baseline is 3. The tool description doesn't add any parameter information beyond what's in the schema. The schema already describes 'id' as 'ID dell'opportunità (es. 13x42)' (ID of the opportunity, e.g., 13x42), which covers the parameter semantics 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 tool's purpose: 'Recupera i dettagli completi di un'opportunità tramite ID' (Retrieves complete details of an opportunity via ID). It specifies the verb ('recupera' - retrieves), resource ('opportunità' - opportunity), and mechanism ('tramite ID' - via ID). However, it doesn't explicitly differentiate from sibling tools like 'list_opportunita' or 'search_opportunita', which would require 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 provides no guidance on when to use this tool versus alternatives. There are multiple sibling tools dealing with opportunities (list_opportunita, search_opportunita, create_opportunita, update_opportunita), but the description doesn't indicate this is for retrieving details of a specific known opportunity versus listing/searching for opportunities. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elenca le attività associate a un'opportunità
| Name | Required | Description | Default |
|---|---|---|---|
| opportunita_id | Yes | ID dell'opportunità (es. 13x42) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists activities, implying a read-only operation, but doesn't clarify aspects like pagination (the 'limit' parameter suggests it), error handling, authentication needs, rate limits, or what the output looks like. For a tool with no annotation coverage, this leaves significant behavioral gaps.
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 in Italian: 'Elenca le attività associate a un'opportunità.' It's front-loaded with the core purpose and wastes no words. Every part of the sentence contributes directly to understanding the tool's function.
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 (2 parameters, no output schema, no annotations), the description is incomplete. It lacks details on output format, error cases, pagination behavior (implied by 'limit'), and how it differs from sibling tools. Without annotations or an output schema, the description should provide more context to be fully 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 description coverage is 50% (only 'opportunita_id' has a description). The description doesn't add any parameter-specific information beyond what's in the schema. It implies the tool uses 'opportunita_id' to filter activities, but doesn't explain the 'limit' parameter's role or provide examples. With low schema coverage, the description fails to compensate for undocumented parameters.
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 tool's purpose: 'Elenca le attività associate a un'opportunità' (List the activities associated with an opportunity). It specifies the verb 'elenca' (list) and the resource 'attività' (activities) with the context 'associate a un'opportunità' (associated with an opportunity). However, it doesn't explicitly differentiate from sibling tools like 'get_opportunita' or 'list_opportunita', which focus on opportunities themselves rather than their associated activities.
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 doesn't mention prerequisites, exclusions, or compare it to sibling tools such as 'list_opportunita' (which lists opportunities) or 'get_opportunita' (which retrieves a single opportunity). Without this context, users must infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Elenca le opportunità con filtri opzionali
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Numero massimo di risultati | |
| stato | No | Stato (es. Prospecting, Qualification, Closed Won) | |
| search | No | Testo da cercare nel nome opportunità |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists opportunities with optional filters but does not mention whether it's read-only, safe, or has any side effects. For a list operation, this omission is significant as it fails to clarify permissions, rate limits, or output format, leaving the agent with incomplete behavioral understanding.
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 in Italian that directly states the tool's function. It is front-loaded with the core action ('Elenca le opportunità') and includes key detail ('con filtri opzionali'). There is no wasted verbiage, making it appropriately concise for its purpose, though it could be more structured with additional context.
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 annotations and no output schema, the description is incomplete for a tool with three parameters and multiple siblings. It lacks details on behavioral traits, output format, and differentiation from similar tools. For a list operation in a CRM-like context, more information on scope, pagination, or error handling would be needed to ensure the agent can use it correctly.
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 100%, so the schema fully documents the three parameters (limit, stato, search). The description adds no additional meaning beyond implying filtering capabilities, which is already covered by the schema. With high schema coverage, the baseline score of 3 is appropriate, as the description does not compensate but also does not detract from parameter understanding.
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 'Elenca le opportunità con filtri opzionali' clearly states the verb ('Elenca' - list) and resource ('opportunità' - opportunities), making the basic purpose understandable. However, it does not distinguish this tool from sibling tools like 'search_opportunita' or 'get_opportunita', leaving ambiguity about when to use each. The description is not tautological but lacks specificity for differentiation.
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 like 'search_opportunita' or 'get_opportunita'. It mentions optional filters but does not specify contexts, prerequisites, or exclusions. Without explicit when/when-not instructions or named alternatives, usage is implied but unclear, leading to potential misuse among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Esegue una query VTQL grezza su VTENext (solo lettura)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Query VTQL (es. SELECT * FROM Potentials LIMIT 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is read-only ('solo lettura'), which is helpful, but lacks critical details: it doesn't mention authentication requirements, rate limits, error handling, what happens with malformed queries, or the format/scope of results. For a raw query tool with zero annotation coverage, this leaves significant behavioral gaps.
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 concise and front-loaded in a single sentence. It efficiently conveys the core action and constraint ('solo lettura') without unnecessary words. However, it could be slightly more structured by explicitly separating purpose from limitations or adding a brief example to enhance clarity without sacrificing brevity.
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 complexity of executing raw queries on a system like VTENext, the description is incomplete. With no annotations and no output schema, it fails to address key aspects: authentication needs, query language specifics, result format, error conditions, or performance implications. Sibling tools suggest this is part of a CRM/opportunity management system, but the description doesn't contextualize VTQL or its relation to other tools, leaving significant gaps for safe and effective use.
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 adds minimal parameter semantics beyond the schema. It mentions 'query VTQL grezza' (raw VTQL query), which aligns with the schema's parameter description. However, with 100% schema description coverage, the schema already documents the single 'query' parameter well. The description doesn't add syntax examples, VTQL dialect details, or constraints beyond what the schema provides, meeting the baseline for 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 the tool's purpose: 'Esegue una query VTQL grezza su VTENext (solo lettura)' which translates to 'Executes a raw VTQL query on VTENext (read-only)'. It specifies the verb ('executes'), resource ('VTQL query'), and target system ('VTENext'), but doesn't explicitly differentiate from sibling tools like 'search_opportunita' or 'list_opportunita' which might also query data.
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 minimal usage guidance. It mentions '(solo lettura)' indicating read-only use, but offers no explicit guidance on when to use this tool versus alternatives like 'search_opportunita' or 'list_opportunita', nor does it specify prerequisites, limitations, or appropriate contexts for raw VTQL queries versus structured search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cerca contatti per nome, email o azienda
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Testo da cercare | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the search functionality but doesn't disclose important behavioral aspects like whether this is a read-only operation, what permissions are required, how results are returned, or any rate limits. The description is minimal and lacks behavioral context.
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 extremely concise - a single sentence that directly states the tool's function. There's zero waste or unnecessary information, making it highly efficient for an agent to parse.
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 search tool with 2 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, how results are structured, or provide enough behavioral context. The minimal description leaves significant gaps for proper tool understanding.
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% (only 'q' has a description). The description adds some value by specifying what fields are searched (name, email, company), which helps understand the 'q' parameter's purpose. However, it doesn't explain the 'limit' parameter at all. Baseline 3 is appropriate given partial 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 the tool's purpose with a specific verb ('Cerca' - Search) and resource ('contatti' - contacts), and specifies the searchable fields (name, email, company). It doesn't explicitly distinguish from sibling tools like 'search_opportunita', but the resource type differentiation is clear.
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 is provided about when to use this tool versus alternatives. While it's clearly a search tool for contacts, there's no mention of when to use it instead of other search or listing tools, or any prerequisites for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cerca opportunità per nome
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Testo da cercare nel nome dell'opportunità | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions searching by name but doesn't disclose behavioral traits like whether it's read-only (likely, but not stated), if it requires authentication, rate limits, pagination, or what happens on no matches. The description is minimal and fails to compensate for the lack of 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, efficient sentence in Italian ('Cerca opportunità per nome'), which is appropriately concise and front-loaded. However, it's under-specified rather than optimally concise, as it lacks necessary details, but within its brevity, it wastes no words.
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 (search function with 2 parameters), no annotations, no output schema, and 50% schema coverage, the description is incomplete. It doesn't explain return values, error conditions, or usage context, leaving significant gaps for an AI agent to understand and invoke the tool correctly.
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% (only 'q' has a description). The description adds no parameter semantics beyond what's in the schema—it doesn't explain 'q' further or clarify 'limit' (e.g., default value, range, or units). With partial schema coverage, the description doesn't compensate, so it meets the baseline for minimal value added.
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 'Cerca opportunità per nome' (Search opportunities by name) states a clear verb ('cerca') and resource ('opportunità'), but it's vague about scope and doesn't distinguish from siblings like 'list_opportunita' or 'search_contatti'. It specifies searching by name, which helps, but lacks detail on what constitutes an 'opportunità' or the search mechanism.
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 is provided on when to use this tool versus alternatives such as 'list_opportunita' (which might list all opportunities) or 'search_contatti' (for searching contacts). The description implies usage for name-based searches but doesn't specify contexts, prerequisites, or exclusions, leaving the agent to infer 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.
Aggiorna i dati di un'opportunità esistente
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID dell'opportunità (es. 13x42) | |
| stato | No | Nuovo stato | |
| importo | No | Nuovo importo | |
| descrizione | No | Note aggiornate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'aggiorna' implies a mutation operation, it doesn't specify required permissions, whether changes are reversible, rate limits, or what happens when only partial fields are provided. For a mutation tool with zero annotation coverage, this is inadequate.
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 in Italian that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded with the essential information.
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 mutation tool with 4 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after the update, what values are returned, error conditions, or provide any context about the opportunity system. The agent would need to guess about the tool's behavior and outcomes.
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 100%, so all parameters are documented in the schema. The description doesn't add any parameter semantics beyond what's already in the schema - it doesn't explain relationships between parameters, validation rules, or provide examples. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('aggiorna' - updates) and resource ('dati di un'opportunità esistente' - data of an existing opportunity), making the purpose immediately understandable. It distinguishes from sibling tools like 'create_opportunita' (creates new) and 'get_opportunita' (reads), though it doesn't explicitly mention these distinctions.
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 like 'create_opportunita' or 'add_nota_opportunita'. It doesn't mention prerequisites, error conditions, or any context about when this update operation is appropriate versus other modification tools.
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. Dates show when Glama detected each change.
v1.0.0add_nota_opportunitacreate_opportunitadescribe_moduloget_opportunitalist_attivita_opportunitalist_opportunitaquery_rawsearch_contattisearch_opportunitaupdate_opportunitaEach tool has a clearly distinct purpose with no ambiguity. For example, list_opportunita retrieves multiple records with filters, get_opportunita fetches a single record by ID, and search_opportunita finds records by name. The tools target different resources (opportunità, contatti, modulo) and actions (create, update, list, search, describe, query).
All tool names follow a consistent verb_noun pattern in snake_case. Verbs like add, create, describe, get, list, query, search, and update are used predictably with corresponding nouns (e.g., add_nota_opportunita, create_opportunita, describe_modulo). There are no deviations in naming conventions.
With 10 tools, the count is well-scoped for managing opportunities and related data in VTENext. Each tool serves a clear purpose, such as CRUD operations for opportunities, searching contacts, listing activities, and raw queries. No tool feels redundant or unnecessary for the server's domain.
The tool set provides complete coverage for the VTENext opportunity management domain. It includes full CRUD (create, get, update, list/search) for opportunities, plus related operations like adding notes, listing activities, searching contacts, describing modules, and raw queries. There are no obvious gaps, and agents can handle typical workflows without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
GibsonAI MCP server: manage your databases with natural language
Cross-product MCP server for CRM, LeadKit, ProjectKit, Bookio. 10 action types, MIT open spec.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Castaldo-Solutions/mcp-vtenext'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
