The Itcons.app MCP Server connects AI assistants to the Itcons.app business operations platform, enabling both read and write operations.
Read Capabilities:
Check connection – Validate configured credentials
List catalogs – Retrieve work order types, work report models, projects, clients, statuses, users, and resources
Search work orders – Filter by name, type, status, project, priority, creator, and assignee
List pending work orders – Shortcut for work orders with pending status (status 4)
Search work reports – Filter by report ID, model, or date
List work reports by date – Retrieve reports for a specific date (YYYY-MM-DD or DD/MM/YYYY)
List today's work reports – Retrieve today's reports, respecting a configured timezone
Write Capabilities:
Create work order – With name, project, type, description, priority, and ERP ID
Create user – With credentials, roles, and permissions
Create project – Optionally linked to a client
Create client – With contact and identification details
Deployment modes: Runs locally via stdio for desktop clients, or remotely via HTTP with OAuth support for hosted clients (e.g., ChatGPT Apps). All operations are scoped to the configured Itcons.app workspace.
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., "@Itcons.app MCP Server show me today's work reports"
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.
Model Context Protocol server for connecting AI assistants to Itcons.app.
Itcons.app is a business operations platform for managing work reports, work orders, projects, clients, users, and related operational resources. It is designed to help teams digitize field and office workflows around daily reports, assignments, task tracking, and service execution.
This package can run in two modes:
Local stdio mode for clients such as Codex, Claude Desktop, and other local MCP hosts.
Remote HTTP mode for hosted MCP clients such as ChatGPT Apps or other clients that require a public HTTPS MCP endpoint.
With this MCP server, an assistant can query Itcons.app data, search work reports and work orders, list operational catalogs such as statuses, users, resources, projects, and clients, and create supported Itcons.app records when the configured user has permission to do so.
Authenticate with POST /api/login_check.
Use Bearer authentication for Itcons.app API calls.
Resolve the API base URL from ITCONS_DOMAIN.
List statuses, users, resources, clients, projects, work order types, and work report models.
Search work reports and work orders.
Create clients, projects, users, and work orders.
Webhooks are intentionally not included in this MCP server. The remote HTTP mode is for MCP client traffic, not inbound Itcons.app webhook delivery.
Related MCP server: CashChat MCP Server
From npm:
npm install -g @itcons-app/mcpFrom this repository:
npm install
npm run checkIf Node was installed with Homebrew and node/npm are not in your PATH, use:
/opt/homebrew/opt/node/bin/npm install
/opt/homebrew/opt/node/bin/npm run checkThe local stdio server reads Itcons.app credentials from environment variables.
ITCONS_DOMAIN=demo
ITCONS_USERNAME=user@example.com
ITCONS_PASSWORD=change-me
ITCONS_TIMEZONE=Europe/MadridFor https://demo.itcons.app, set:
ITCONS_DOMAIN=demoYou may use an existing Bearer token instead of username/password:
ITCONS_DOMAIN=demo
ITCONS_TOKEN=ey...ITCONS_API_BASE_URL is optional. If omitted, the server uses:
https://ITCONS_DOMAIN.itcons.app/apiExample configuration using a globally installed package:
{
"mcpServers": {
"itcons-app": {
"command": "itcons-app-mcp",
"env": {
"ITCONS_DOMAIN": "demo",
"ITCONS_USERNAME": "user@example.com",
"ITCONS_PASSWORD": "change-me",
"ITCONS_TIMEZONE": "Europe/Madrid"
}
}
}
}Start the remote MCP server:
PORT=3000 \
HOST=127.0.0.1 \
ITCONS_MCP_PUBLIC_URL=https://mcp.example.com \
ITCONS_OAUTH_CLIENT_ID=itcons-app-chatgpt \
ITCONS_OAUTH_CLIENT_SECRET=change-me \
npm run start:httpThe remote server exposes:
MCP Streamable HTTP endpoint: https://mcp.example.com/mcp
Reports-only MCP endpoint for public ChatGPT apps: https://mcp.example.com/reports-mcp
SSE-compatible endpoint: https://mcp.example.com/sse
OAuth authorize URL: https://mcp.example.com/oauth/authorize
OAuth token URL: https://mcp.example.com/oauth/token
OAuth dynamic client registration URL: https://mcp.example.com/oauth/register
Health check: https://mcp.example.com/health
For ChatGPT's "Create app" screen, use the public MCP URL:
https://mcp.example.com/mcpFor a narrow public app focused only on work reports, use:
https://mcp.example.com/reports-mcpIf a client specifically asks for an SSE URL, use:
https://mcp.example.com/sseWhen the user connects the app, the OAuth login page asks for their Itcons.app email and password. If ITCONS_DOMAIN_LOOKUP_URL is configured, the page tries to detect the Itcons.app domain from the email; otherwise the user can type the domain manually. The server validates those credentials with Itcons.app and stores an in-memory session token for subsequent MCP calls.
Example configuration using a local checkout:
{
"mcpServers": {
"itcons-app": {
"command": "node",
"args": [
"/absolute/path/to/itcons-app-mcp/src/index.js"
],
"env": {
"ITCONS_DOMAIN": "demo",
"ITCONS_USERNAME": "user@example.com",
"ITCONS_PASSWORD": "change-me",
"ITCONS_TIMEZONE": "Europe/Madrid"
}
}
}
}Read-only tools:
itcons_check_connection
itcons_list_workorder_types
itcons_list_work_report_models
itcons_list_projects
itcons_list_clients
itcons_list_statuses
itcons_list_users
itcons_list_resources
itcons_search_workorders
itcons_list_pending_workorders
itcons_search_work_reports
itcons_list_work_reports_by_date
itcons_list_today_work_reports
Create tools:
itcons_create_workorder
itcons_create_user
itcons_create_project
itcons_create_client
Reports-only profile tools exposed by /reports-mcp:
itcons_check_connection
itcons_list_work_report_models
itcons_search_work_reports
itcons_list_work_reports_by_date
itcons_list_today_work_reports
Tool annotations:
Read-only tools set readOnlyHint: true, destructiveHint: false, and openWorldHint: false because they only read private Itcons.app data.
Create tools set readOnlyHint: false, destructiveHint: false, and openWorldHint: false because they create records only inside a private Itcons.app workspace and do not publish to public internet surfaces.
Variable | Required | Description |
| Yes | Installation subdomain. For |
| Yes, unless | Itcons.app username or email. |
| Yes, unless | Itcons.app password. |
| No | Existing Bearer token. If set, login is skipped. |
| No | Alternative API base URL. |
| No | Time zone used by |
| No | HTTP server port. Defaults to |
| No | HTTP server bind host. Defaults to |
| Yes for remote mode | Public HTTPS origin, for example |
| No | Remote MCP endpoint path. Defaults to |
| No | SSE-compatible endpoint path. Defaults to |
| Recommended for remote mode | Comma-separated allowed Host headers, for example |
| No | OAuth client ID expected by the remote server. Defaults to |
| Recommended for remote mode | OAuth client secret expected by the remote server. |
| Recommended for public apps | JSON file used to persist dynamically registered OAuth clients. |
| No | Endpoint used to detect the Itcons.app domain from an email. Defaults to |
| No | Set to |
Work order pending status is 4.
itcons_search_workorders fetches /workorders and applies filters locally.
itcons_list_work_reports_by_date filters on the date field returned by /2.0/partes.
itcons_create_workorder sends status: 4 and isArchived: 0.
itcons_create_user sends an array payload to /2.0/users, matching the current API.
itcons_create_client sends an array payload to /clients and returns the first array item when applicable.
Run syntax checks:
npm run checkRun a local MCP discovery smoke test:
npm run smokeRun a local HTTP MCP smoke test:
npm run smoke:httpRun a live read-only HTTP smoke test against Itcons.app:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:http:liveRun a live OAuth smoke test that simulates a ChatGPT-style connection:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:oauth:liveRun a live read-only smoke test against Itcons.app:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:livePublish the public npm package:
npm publish --access publicDo not commit .env files or real credentials. The package excludes .env, node_modules, and debug logs from npm publication.
Create tools perform real writes in Itcons.app. Use them only with credentials and installations where the MCP client is allowed to make changes.
The built-in remote OAuth implementation stores authorization codes and access tokens in memory. Use a single Node.js process for the first deployment, or replace the in-memory maps with persistent storage such as Redis before running multiple replicas.
Validate the configured Itcons.app credentials by listing private work order types without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds context that it lists private work order types to validate credentials, going beyond the annotations 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?
Single sentence that is front-loaded with purpose and efficiently conveys all necessary information without waste.
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 no-parameter, no-output-schema tool, the description fully covers what the tool does and its read-only nature, making it complete for its 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?
Input schema has 0 parameters, so baseline is 4. Description adds no parameter info as none is needed.
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 (validate credentials), the method (listing private work order types), and the side effect (no data modification). It distinguishes from sibling tools which are creation or listing tools for different purposes.
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 as a first step to validate credentials before other operations, but does not explicitly state when to use versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new client inside the user's private Itcons.app workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Client name. | |
| address | No | Address. | |
| cif | No | CIF/NIF. | |
| phone | No | Phone. | |
| No | Email address. | ||
| erpid | No | Optional ERP ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only (write operation) and non-destructive. The description adds no additional behavioral context beyond confirming creation, which aligns with 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?
One sentence, 12 words, front-loaded with key action and scope. No redundant 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?
Adequate but missing return value description. With no output schema, the agent might benefit from knowing what is returned (e.g., client ID). Does not mention side effects or post-conditions.
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 100% parameter description coverage, so baseline 3 applies. The description does not add extra meaning beyond schema; terms like CIF are not explained.
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 'Create a new client' with specific resource and scope, distinguishing it from sibling tools like itcons_create_project or itcons_create_user.
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, prerequisites, or context. Sibling tools include other create and list operations, but no differentiation provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project or assignment inside the user's private Itcons.app workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name. | |
| No | Optional project email. | ||
| info | No | Optional project information. | |
| erpid | No | Optional ERP ID. | |
| client | No | Optional client ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, so description aligns with write operation. However, description adds no additional behavioral context beyond annotations, such as what happens on creation, permission needs, or side effects.
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, no redundancy. Could be slightly more informative without sacrificing conciseness.
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, and description does not explain return values, error handling, or clarify 'project or assignment' ambiguity. With 5 parameters, 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%, but descriptions are minimal. The tool description does not add meaning beyond the schema's basic notes, so 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?
Clearly states 'Create a new project or assignment', with specific verb and resource. Differentiates from sibling create tools like itcons_create_client, itcons_create_user, etc.
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, no when-not-to-use or exclusions provided. Simply restates the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new user inside the user's private Itcons.app workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Username. | |
| Yes | Email address. | ||
| password | Yes | Initial password. | |
| roles | No | Role ID: 1 administrator, 2 mobile user, 3 project manager. | 2 |
| firstname | No | First name. | |
| lastname | No | Last name. | |
| dni | No | DNI/NIF. | |
| erpid | No | Optional ERP ID. | |
| workorder_active | No | Can use work orders. | |
| workorder_create | No | Can create work orders. | |
| projects_create | No | Can create projects. | |
| modelo_id | No | Work report model IDs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=false (write operation) and destructiveHint=false. The description simply restates this intention without adding deeper behavioral context such as side effects (e.g., email notifications), error handling for duplicate users, or access control requirements. It is 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?
The description is a single, front-loaded sentence that efficiently conveys the core purpose with no wasted words. It is appropriately sized for 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 complexity (12 parameters, write operation, no output schema), the description lacks information on what the tool returns, how it handles duplicates, or whether it triggers downstream effects. It is minimally complete but leaves significant gaps for agent 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?
Input schema has 100% description coverage for all 12 parameters, including docs for enums and defaults. The tool description adds no additional meaning beyond the schema, so baseline score 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 the verb 'Create' and resource 'new user', with a specific location: 'inside the user's private Itcons.app workspace.' This succinctly distinguishes it from sibling tools like itcons_create_client or itcons_list_users.
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 such as itcons_create_client or itcons_create_project. It lacks any when-to-use or when-not-to-use context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new work order inside the user's private Itcons.app workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Work order name. | |
| project | Yes | Project/assignment ID. | |
| type | Yes | Work order type ID. | |
| priority | No | Priority. | |
| info | No | Optional work order description. | |
| erpid | No | Optional ERP ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds minimal extra context beyond stating it creates a new work order in a private workspace, which aligns with annotations but does not disclose additional behavioral traits.
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 succinct sentence that includes the action, resource, and context. It is front-loaded and contains no unnecessary 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?
The description omits critical information for a creation tool, such as what the response contains (e.g., created work order ID) and whether there are permission requirements. Given the lack of an output schema, this gap is significant.
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 baseline is 3. The description does not elaborate on parameters beyond what the schema already provides, such as dependencies or usage hints, thus adding no extra semantic value.
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 specifies the action 'create', the resource 'work order', and the context 'inside the user's private Itcons.app workspace'. This clearly distinguishes it from siblings that list or search work orders or create other entities like clients or projects.
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 does not indicate when to use this tool versus alternatives (e.g., when to create vs. search). It lacks prerequisites or conditions, such as needing a valid project ID, and provides no guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private clients from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description only restates 'without modifying data' without adding new behavioral details like pagination behavior or default limits.
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 of 9 words, highly concise with no redundant 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 simple list tool with one optional parameter and explicit read-only annotation, the description is complete and adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single 'limit' parameter with a description. The tool description adds no additional meaning beyond the schema, so baseline score 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 the verb 'list', the resource 'private clients', and the scope 'from Itcons.app', distinguishing it from sibling tools like itcons_create_client. It also explicitly notes 'without modifying data', aligning with readOnlyHint.
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, such as itcons_search_workorders for other entities, or whether any prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private pending work orders from Itcons.app. Pending is status 4 and no data is modified.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Optional project/assignment ID. | |
| type | No | Optional work order type ID. | |
| priority | No | Optional priority. Accepts urgente, alta, media, baja, or API labels such as priority.alta. | |
| assigned_to | No | Optional assigned user filter. Matches username, name, email, or user ID. | |
| name | No | Optional case-insensitive work order name search. | |
| created_by | No | Optional creator username filter. | |
| limit | No | Maximum matching items to return. | |
| offset | No | Pagination offset after filtering. | |
| include_raw | No | Include full raw work order objects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds value by confirming 'no data is modified' and revealing the internal status value (4). However, it does not disclose limitations like pagination default behavior or what 'private' implies.
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 two concise sentences, front-loaded with action and resource. Every word earns its place; no redundant 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?
Given the 9 parameters and lack of output schema, the description is minimal. It omits details on return format, how 'private' filters work, and pagination nuances. Schema covers parameter descriptions, but overall context for a new agent is insufficient.
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 9 parameters are fully described in the input schema (100% coverage), so the description adds no additional parameter-level meaning. The general note about pending status 4 is helpful context but not directly about 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 lists pending work orders from Itcons.app, specifying the exact status (4) and that no data is modified. This clearly distinguishes it from sibling tools like itcons_search_workorders which likely cover broader scopes.
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 gives no guidance on when to use this tool versus alternatives such as itcons_search_workorders. It does not mention that for non-pending work orders the search tool should be used, leaving the agent without explicit decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private projects and assignments from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this by stating 'without modifying data'. It adds the context of listing 'private' projects, but does not disclose any additional behavioral traits such as pagination or response format.
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, short sentence that conveys the essential action and scope without extraneous words. It is perfectly concise.
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 low complexity (one optional parameter, no output schema), the description adequately covers the tool's purpose. It mentions listing 'private projects and assignments', which provides enough context for an agent to understand the scope, though it could clarify what 'assignments' entails.
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 single parameter 'limit' has complete schema coverage with a description in the input schema. The tool description does not add any further semantics or usage hints for this parameter, so it meets the 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 description clearly states 'List private projects and assignments', specifying a concrete verb and resource. It distinguishes from sibling tools like 'itcons_list_clients' by mentioning 'projects' and 'assignments'.
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 says 'without modifying data', implying safe read-only usage, but provides no explicit guidance on when to use versus alternatives or when not to use. The differentiation from other list tools is implicit via the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private resources from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context by explicitly stating 'without modifying data', which reinforces the read-only behavior. However, it does not disclose other potential behaviors such as authentication requirements or response format.
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 with no wasted words. It is front-loaded and efficiently conveys the core purpose and read-only nature.
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 list tool with one optional parameter and no output schema, the description provides sufficient information. It could be improved by clarifying what constitutes a 'resource' in this context, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter (limit) with full description and constraints, so the description need not add more. The tool description does not mention the parameter, but schema coverage is 100%, so the baseline of 3 applies.
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 'List' and the resource 'private resources', and specifies it does not modify data. However, 'resources' is somewhat vague compared to sibling tools that list specific entities like clients or projects.
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 only mentions that the tool does not modify data, which implies safe inspection, but it provides no guidance on when to use this tool versus other list tools like itcons_list_clients or itcons_list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private work report and work order statuses from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Optional status type filter. | |
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this with 'without modifying data' but adds no new behavioral details beyond the 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?
Single sentence, no fluff, front-loaded with the action. Every word 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?
For a simple list tool with optional filters, the description is adequate. It could mention the output format but is otherwise complete given the lack of output schema.
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 both parameters. The description does not add additional meaning or link to the parameters, so it provides no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'private work report and work order statuses', distinguishing it from siblings like itcons_list_workorder_types or itcons_list_work_reports_by_date. The addition of 'private' and 'without modifying data' adds specificity.
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 itcons_list_workorder_types or itcons_search_workorders. It only states what it does, without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List today's private work reports in Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Optional work report model ID. | |
| limit | No | Maximum matching items to return. | |
| offset | No | Pagination offset for the API request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only operation. The description adds the specificity of 'private work reports' and reaffirms no data modification, providing useful context beyond the 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, front-loaded sentence with no wasted words. Every word contributes to understanding the tool's purpose and behavior.
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 rich schema (all parameters described) and annotations (safety info), the description is largely complete. It could mention that results are paginated via limit/offset, but this is implied by the parameters. No output schema is present, but for a simple list tool the return format is somewhat obvious.
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 provides 100% coverage for all three parameters (model, limit, offset) with clear descriptions. The description adds no additional parameter-level meaning, so a baseline score 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 it lists today's private work reports, specifying both the time frame and visibility scope. This distinguishes it from sibling tools like itcons_list_work_reports_by_date, which likely covers different date ranges.
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 retrieving today's private reports without data modification. However, it does not explicitly exclude use cases (e.g., when needing reports from other dates) or mention alternatives, though the scope is clear from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private users from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description redundantly states 'without modifying data' but adds no additional behavioral details such as authentication requirements or data consistency guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-formed sentence that immediately conveys the core function. No extraneous words; front-loaded with the verb and noun.
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 list tool with one optional parameter and no output schema, the description adequately covers its purpose. It could optionally mention default behavior (e.g., pagination or ordering) but is not deficient.
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 sole parameter 'limit' is fully documented in the input schema (100% coverage). The description does not add extra meaning beyond what the schema provides, meeting baseline expectations.
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 ('List'), resource ('private users'), and explicitly declares no data modification, effectively distinguishing it from sibling tools like itcons_create_user or itcons_list_clients.
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 this tool vs alternatives. The name and description imply its purpose for listing users, but no context on exclusions or preferred scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private work order types from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description's claim of 'without modifying data' adds minimal value. No additional behavioral traits (e.g., pagination, rate limits) are disclosed beyond the 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 one concise sentence with no unnecessary words. It is front-loaded with the verb and resource, and every word serves a 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?
With no output schema, the description should provide some hint about the return format (e.g., list of type names or objects). It does not, leaving the agent to guess the structure of the output.
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% coverage for the single parameter 'limit', and its description is already present in the schema. The tool description does not add any meaning beyond what the schema provides.
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 'List' and the resource 'private work order types', distinguishing it from sibling tools that list other entities like clients, projects, or statuses. However, it could be more specific about what constitutes a work order type.
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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context. The purpose is clear enough for an agent to infer usage, but no explicit when-to-use or when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private work report models from Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum items to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true and destructiveHint=false, and the description merely repeats this by stating 'without modifying data'. No additional behavioral traits (e.g., authentication needed, pagination) are disclosed.
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 efficiently conveys the tool's purpose without superfluous 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 lack of output schema, the description could have explained the return format or pagination behavior. It is adequate for a simple tool but leaves gaps about what exactly is returned.
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% for the single 'limit' parameter, which is adequately described in the schema. The description adds no extra meaning or usage guidance beyond what the schema provides.
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), the resource (private work report models), and the scope (from Itcons.app). It also clarifies it is a read-only operation, which helps differentiate from other list tools among siblings.
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 this tool versus alternatives like itcons_list_work_reports_by_date or itcons_search_work_reports. The description does not provide usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private work reports matching a specific date in Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Report date in YYYY-MM-DD or DD/MM/YYYY format. | |
| model | No | Optional work report model ID. | |
| limit | No | Maximum matching items to return. | |
| offset | No | Pagination offset for the API request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'without modifying data' which aligns but doesn't provide additional behavioral context such as pagination behavior, rate limits, or return format. Minimal added 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 concise sentence that conveys the core purpose without extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward (4 params, required only date, no output schema), but the description lacks context about what 'private' means (user-specific?) and does not hint at the response structure. Adequate but not enriched.
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 parameters. The description adds no new parameter information beyond that, meeting the baseline of 3.
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 'List private work reports matching a specific date' with a specific verb and resource. It distinguishes itself from siblings like 'itcons_list_today_work_reports' and 'itcons_search_work_reports' by emphasizing the date filter and read-only nature.
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 when not to use it or point to sibling tools. The only hint is 'without modifying data', but that is redundant with annotations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search private Itcons.app work orders with optional filters without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Optional work order status. Use 4/pendiente, 5/en-ejecucion, 6/completado, or 7/anulado. | |
| project | No | Optional project/assignment ID. | |
| type | No | Optional work order type ID. | |
| priority | No | Optional priority. Accepts urgente, alta, media, baja, or API labels such as priority.alta. | |
| assigned_to | No | Optional assigned user filter. Matches username, name, email, or user ID. | |
| name | No | Optional case-insensitive work order name search. | |
| created_by | No | Optional creator username filter. | |
| limit | No | Maximum matching items to return. | |
| offset | No | Pagination offset after filtering. | |
| include_raw | No | Include full raw work order objects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description repeats 'without modifying data', which aligns. However, beyond that, no additional behavioral traits are disclosed (e.g., pagination behavior, ordering, or default results). The description adds minimal extra 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 a single sentence that efficiently conveys the purpose, resource, and key constraint (read-only). No extraneous words or redundant information. It is appropriately 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 the high parameter count and lack of an output schema, the description is somewhat incomplete. It does not mention return format, pagination details, or what 'private' implies. However, the schema covers the parameters, and the annotations cover safety. A more complete description would explain behavior at limits or ordering.
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 10 parameters have descriptions in the input schema (100% coverage), so the description does not need to add parameter details. The description's generic mention of 'optional filters' does not enhance understanding beyond what the schema provides, meriting a baseline score of 3.
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 'Search private Itcons.app work orders' with a specific verb and resource. It also clarifies the read-only nature ('without modifying data'), distinguishing it from sibling tools like itcons_create_workorder. This makes the 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 implies this tool is for searching work orders with optional filters, but it does not explicitly state when to use this versus alternatives (e.g., itcons_list_pending_workorders). No guidance on when not to use or which alternative to choose is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search private work reports by ID or model in Itcons.app without modifying data.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Work report ID. | |
| model | No | Work report model ID. | |
| limit | No | Maximum items to return. | |
| offset | No | Pagination offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces 'without modifying data', adding minimal extra behavioral context beyond the 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 sentence that packs key information (verb, resource, scope, safety). It is front-loaded and concise with no wasted 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?
The description omits behavior when no parameters are provided (all are optional), and does not explain the return format or pagination details. This leaves the agent with incomplete guidance for correct invocation.
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 provides 100% description coverage for all four parameters. The description only mentions 'by ID or model', which maps to id and model, adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'private work reports', with specific scope 'by ID or model'. This distinguishes it from sibling list tools that do not filter by specific IDs.
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 using this tool when searching by ID or model, providing clear context. However, it does not explicitly state when not to use it or name alternatives, missing some guidance.
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.5.1itcons_check_connectionitcons_create_clientitcons_create_projectitcons_create_useritcons_create_workorderitcons_list_clientsitcons_list_pending_workordersitcons_list_projectsitcons_list_resourcesitcons_list_statusesitcons_list_today_work_reportsitcons_list_usersitcons_list_work_report_modelsitcons_list_work_reports_by_dateitcons_list_workorder_typesitcons_search_work_reportsitcons_search_workordersScored across 17 tools
Each tool targets a specific entity and action (create, list, search) with no overlap. For example, itcons_create_client is distinct from itcons_list_clients, and separate tools exist for workorder-related operations like create, list, pending, search.
All tools follow a consistent 'itcons_verb_noun' pattern (e.g., itcons_create_client, itcons_list_projects, itcons_search_workorders). Underscores and naming are uniform.
17 tools is slightly above the ideal range but still reasonable for a project management system covering multiple entities (clients, projects, users, work orders, work reports). Each tool serves a distinct purpose.
The tool set provides create and read operations for key entities but lacks update, delete, or any write operations for work reports, resources, and statuses. This forces agents to abandon workflows when modifications are needed, leaving dead ends.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Connects AI assistants to QCDatabase.AI for everyday construction quality-control work.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Connect AI agents to 1000+ apps with managed authentication and tool-calling.