Click on "Install 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., "@ServiceNow Incident MCP Server search incidents about VPN"
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.
A production-ready Model Context Protocol (MCP) server that turns any MCP-compatible AI assistant (Claude, Cursor, etc.) into an AI-powered ServiceNow Incident Management Assistant. It exposes ServiceNow incidents, users, CMDB records, and knowledge articles through clean, validated MCP tools.
AI Assistant ──► MCP Server (Node.js + TypeScript) ──► ServiceNow REST API ──► ServiceNow Instance12 MCP tools across three phases (read, actions, AI-powered helpers).
Reusable ServiceNow REST client (Axios) with Basic auth, request timeout, and exponential-backoff retry on transient failures.
Zod-validated inputs for every tool.
Structured logging to stderr with automatic secret redaction — passwords and auth headers are never logged.
Self-contained, deterministic AI tools — no external LLM or API key required.
Modular, enterprise-grade architecture with a full unit-test suite (Vitest).
Related MCP server: snow-mcp
src/
├── clients/
│ └── servicenowClient.ts # Axios wrapper: GET/POST/PATCH, auth, retry, timeout, Table API helpers
├── config/
│ └── env.ts # Zod-validated environment configuration
├── schemas/
│ └── index.ts # Zod input schemas for every tool
├── services/
│ ├── incidentService.ts # incident reads/writes + journal (comments/work notes)
│ ├── userService.ts # sys_user lookups
│ ├── cmdbService.ts # cmdb_ci search
│ ├── knowledgeService.ts # kb_knowledge search
│ ├── aiService.ts # rule-based classification, routing, summaries
│ └── index.ts # service container
├── tools/
│ ├── phase1.read.ts # get_incident, search_incidents, get_user, search_cmdb, get_knowledge_article
│ ├── phase2.actions.ts # create_incident, update_incident, assign_incident, close_incident
│ ├── phase3.ai.ts # classify_incident, incident_summary, suggest_assignment_group
│ ├── helpers.ts # response builders + central error handling
│ └── index.ts # registers all tools
├── types/
│ └── servicenow.ts # shared TypeScript interfaces
├── utils/
│ ├── logger.ts # structured logger + redaction
│ ├── errors.ts # ServiceNowError + safe message mapping
│ └── format.ts # raw ServiceNow record → clean object mappers
├── server.ts # builds the MCP server (config → client → services → tools)
└── index.ts # entrypoint (stdio transport)
tests/ # Vitest unit testsNode.js 18+
A ServiceNow instance and an account with Table API access.
npm install
cp .env.example .env # then edit .env with your instance + credentials
npm run buildVariable | Required | Default | Description |
| yes | — | Instance base URL, e.g. |
| yes | — | Basic auth username |
| yes | — | Basic auth password |
| no |
| Per-request timeout (ms) |
| no |
| Retry attempts on network/429/5xx errors |
| no |
| Default result count for search tools |
| no |
|
|
npm start # run the built server (dist/index.js)
npm run dev # run from TypeScript with hot reloadThe server speaks MCP over stdio.
Tool | Input | Returns |
|
| Number, state, priority, assignment group, assignee, descriptions, timestamps |
|
| Matching incidents (newest first) |
|
| User name, email, phone, title, department |
|
| Matching CMDB CIs |
|
| Matching published KB articles |
Tool | Input | Effect |
|
| Creates an incident → |
|
| Appends work note / comment |
|
| Updates assignment |
|
| Resolves & closes the incident |
Tool | Input | Returns |
|
|
|
|
| Executive summary built from the incident + journal |
|
|
|
classify_incident mirrors ServiceNow's Impact × Urgency → Priority matrix. It infers
impact from the scope of the issue and urgency from time-critical language, both via
documented keyword rules (case-insensitive, first match wins).
Scope detected in the issue text | Impact | Urgency | Priority |
Entire office / company / site / everyone | 1 | 1 | P1 |
Entire team / department / group / floor | 2 | 2 | P2 |
Single employee / one user / "my…" | 3 | 2 | P3 |
Minor / cosmetic / typo / question / slow | 3 | 3 | P4 |
Unrecognized (default) | 3 | 3 | P3 |
Time-critical words (urgent, critical, outage, down, blocked, cannot work,
production, emergency, …) escalate urgency → 1, and priority is recomputed from the matrix:
Impact \ Urgency 1 2 3
1 P1 P2 P3
2 P2 P3 P4
3 P3 P4 P4suggest_assignment_group uses a keyword→group routing table (VPN/network → Network
Operations, email/Outlook → Messaging & Collaboration, password/login → Identity & Access
Management, database/SQL → Database Team, laptop/printer → Desktop Support, phone/call
forwarding → Telephony, application/crash → Application Support), defaulting to Service Desk.
These rules live in
src/services/aiService.tsand are easy to tune for your org's groups.
Add the server to your MCP client config. Use absolute paths and supply credentials via env.
Claude Desktop (claude_desktop_config.json) / Cursor (.cursor/mcp.json):
{
"mcpServers": {
"servicenow": {
"command": "node",
"args": ["/absolute/path/to/servicenow-mcp/dist/index.js"],
"env": {
"SNOW_INSTANCE": "https://dev12345.service-now.com",
"SNOW_USERNAME": "admin",
"SNOW_PASSWORD": "your-password",
"LOG_LEVEL": "info"
}
}
}
}Run npm run build first so dist/index.js exists.
npm test # run the unit test suite (Vitest)
npm run test:coverage
npm run typecheck # tsc --noEmit
npm run lint # eslintTests are fully offline — the ServiceNow client is mocked, and the AI tools are deterministic.
npm run build
npx @modelcontextprotocol/inspector node dist/index.jsThen list tools and try classify_incident / suggest_assignment_group (work offline) or a
read tool against your instance.
Credentials are read only from environment variables; .env is git-ignored.
The logger redacts any password / authorization / token / secret field, and logs
go to stderr only (keeping the MCP stdout channel clean).
All HTTP requests use a configurable timeout and retry transient failures with exponential backoff; 4xx errors (other than 429) fail fast with safe messages.
MIT
Set the assignment group and/or assignee on an incident. Provide at least one of assignmentGroup or assignedTo.
| Name | Required | Description | Default |
|---|---|---|---|
| incidentNumber | Yes | ServiceNow incident number, e.g. "INC0012345" | |
| assignmentGroup | No | Assignment group name | |
| assignedTo | No | Assignee user_name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the action without detailing side effects (e.g., overwrite behavior, notifications, permissions required). For a mutating tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states purpose, second adds key usage constraint. Ideal 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?
Fairly complete for a simple tool, but missing description of return values or error conditions. Could mention success confirmation or any side effects.
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?
Adds value beyond the schema by clarifying that at least one of assignmentGroup or assignedTo must be provided, which is not enforced by the required array. Schema coverage is 100%, so baseline is 3; the extra constraint warrants a 4.
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 'Set' and resource 'assignment group and/or assignee on an incident', distinguishing it from siblings like create_incident, get_incident, and close_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the constraint 'Provide at least one of assignmentGroup or assignedTo', but lacks explicit guidance on when to use this tool versus alternatives like suggest_assignment_group or update_incident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a free-text issue and determine its impact, urgency and priority (P1–P4) using a documented scope-based rule engine. Returns {impact, urgency, priority, reason}.
| Name | Required | Description | Default |
|---|---|---|---|
| issue | Yes | Free-text description of the issue |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions a 'documented scope-based rule engine,' hinting at deterministic behavior, but does not clarify edge cases, idempotency, or what happens if the issue is ambiguous. This is adequate but not comprehensive.
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 sentences: first for purpose and method, second for outputs. No redundant words. Front-loaded with the key action. Could be slightly more structured but is 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?
Given the low complexity (1 parameter, no output schema), the description adequately covers the tool's purpose and return fields. It mentions the output shape (impact, urgency, priority, reason). No critical gaps, though output field formats are not detailed.
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% (the single 'issue' parameter is described). The description adds 'free-text' which matches the schema, but does not provide additional semantic or format details beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes a free-text issue and determines impact, urgency, and priority (P1–P4), using a documented rule engine. The verb 'analyze' and specific output fields distinguish it from siblings like assign_incident or close_incident.
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 when a free-text issue needs classification but provides no explicit guidance on when to use it versus alternatives like suggest_assignment_group, which also classifies. No exclusions or when-not-to scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve and close an incident with the given close notes (and optional close code). Sets state to Closed.
| Name | Required | Description | Default |
|---|---|---|---|
| incidentNumber | Yes | ServiceNow incident number, e.g. "INC0012345" | |
| closeNotes | Yes | ||
| closeCode | No | Close code (default "Solved (Permanently)") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'Sets state to Closed' but lacks details on destructive nature, permissions, or whether resolution requires prerequisites. A minimal disclosure for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with subject, verb, and key details. No redundant words; front-loaded 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?
For a simple 3-param operation without output schema, the description is adequate but minimal. Given no annotations, more context on behavior (e.g., irreversible, required permissions) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters (incidentNumber and closeCode have descriptions). The description merely restates parameter names without adding format, constraints, or default values. closeNotes lacks schema description and description adds no extra meaning.
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 verb and resource: 'Resolve and close an incident'. Distinguishes from siblings like 'update_incident' by specifying the end state 'Closed'.
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?
Implicitly indicates when to use (to close an incident) but no explicit guidance on when not to use or alternatives beyond the context. For example, it doesn't mention using 'update_incident' for non-closing changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new ServiceNow incident. Requires shortDescription; description, caller, assignment group, impact and urgency are optional. Returns the new incident number and sysId.
| Name | Required | Description | Default |
|---|---|---|---|
| shortDescription | Yes | ||
| description | No | ||
| callerId | No | caller user_name or sys_id | |
| assignmentGroup | No | Assignment group name | |
| impact | No | ||
| urgency | 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. It mentions creation, return values, and required/optional fields, but lacks disclosure of side effects, authorization needs, or potential error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words, immediately stating the purpose and key details. Well 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 6 parameters, no output schema, and no annotations, the description covers the core behavior and return values. It could mention error handling or response structure but is adequate for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), but the description adds meaning by listing optional parameters and clarifying that callerId can be a user_name or sys_id, and impact/urgency are optional, going 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 tool creates a new ServiceNow incident, specifies required and optional parameters, and mentions return values (incident number and sysId), distinguishing it from sibling tools like update_incident or close_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that shortDescription is required but does not provide explicit guidance on when to use this tool versus alternatives like assign_incident, classify_incident, or 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.
Retrieve a single ServiceNow incident by its number (e.g. INC0012345). Returns number, state, priority, assignment group, assignee, descriptions and timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| incidentNumber | Yes | ServiceNow incident number, e.g. "INC0012345" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description specifies that it returns number, state, priority, assignment group, assignee, descriptions, and timestamps. Adequate for a read operation, though error behavior not covered.
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, front-loaded with action and resource, 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?
Complete for a simple retrieval tool: specifies input (incident number) and output fields, no output schema needed. No missing context.
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 parameter description. Description adds an example but does not significantly enhance semantic understanding 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?
Description clearly states it retrieves a single ServiceNow incident by its number, listing specific fields returned. Clearly distinct from siblings like search_incidents or create_incident.
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?
Implies usage when incident number is known, but does not explicitly mention alternatives like search_incidents for cases without the number.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search published knowledge base articles by keyword (matches title and body). Returns the article number, title, category and a plain-text excerpt.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Keyword to search knowledge article titles and bodies | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool searches and returns fields, but omits behavioral details like read-only nature, whether it's idempotent, or any rate limits. Adequate but not comprehensive.
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 with no redundancy or irrelevant details. It is well-structured 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?
Given no output schema, the description helpfully lists return fields. However, it lacks details on error handling, ordering of results, or behavior when no matches are found. Still fairly complete for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; only 'keyword' has a description. The description adds that keyword matches title and body, but does not explain the 'limit' parameter (e.g., default, pagination, maximum). This leaves the agent unclear on usage.
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 searches published knowledge base articles by keyword, matching title and body, and lists returned fields. It distinguishes from sibling tools which are predominantly incident-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching knowledge articles but provides no explicit guidance on when to use this tool over alternatives, nor any exclusions such as unpublished articles or specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a ServiceNow user by user_name. Returns name, email, phone, title, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| userName | Yes | The user_name to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description states it returns specific fields (name, email, phone, title, etc.). Does not disclose error handling or permissions, but sufficient for a simple read operation.
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 filler. Efficient and front-loaded with the essential action and return values.
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 for a simple lookup tool with one parameter and no output schema. Mentions returned fields, though 'etc.' is vague. Could be more specific but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of the single parameter with a description. Description adds 'by user_name' but this is redundant; no additional meaning beyond 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?
Clear verb+resource: 'Look up a ServiceNow user by user_name.' Distinct from siblings which are mostly incident-related or CMDB searches.
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?
Implied usage: look up a user by exact username. No explicit when-not-to-use or alternatives. However, context suggests it's the only user lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve an incident plus its comments and work notes, then generate a concise executive summary of the current status.
| Name | Required | Description | Default |
|---|---|---|---|
| incidentNumber | Yes | ServiceNow incident number, e.g. "INC0012345" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes a multi-step process (retrieve then generate) but does not disclose whether the operation is read-only, has side effects, or requires specific permissions. This leaves behavioral uncertainty.
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 sentence, concise and to the point. It could be improved by breaking into separate lines or using bullets for clarity, but it conveys the essential scope without 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?
No output schema is provided, and the description does not clarify what the tool returns (e.g., the summary alone, or also the raw incident/comments/work notes). This ambiguity harms completeness for an AI agent needing to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter, and the description adds a format example ('INC0012345') but does not provide additional semantic nuances beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Retrieve' and 'generate') and a clear resource ('incident plus its comments and work notes'). It distinguishes from siblings like 'get_incident' (which likely returns only incident details) and 'search_incidents' (which performs search, not single retrieval with summary).
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 when a concise executive summary of an incident including comments and work notes is needed. However, it does not explicitly state when not to use this tool or mention alternatives like 'get_incident' for raw data without summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the CMDB (cmdb_ci) for configuration items whose name contains the given text. Returns name, class, category, status, IP and serial number.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | CI name to search for (partial match) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions the search is by name (partial match) and lists return fields, but does not state whether the operation is read-only, pagination behavior, or any side effects. For a search tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded with the action. No wasted words, though could potentially include more detail without losing 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?
The tool has 2 parameters (1 required), no output schema, and no annotations. The description lists return fields, but lacks details on case sensitivity, wildcards, ordering, or pagination. Adequate for a simple search but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'name' has a description). The description adds context that the search is by name and partial match, but does not elaborate on the 'limit' parameter beyond what the schema provides. The description adds some value but not fully compensates for the low 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 it searches the CMDB for configuration items by name and lists the returned fields (name, class, category, status, IP, serial number). It is distinct from sibling tools which are all incident-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or avoid this tool versus alternatives. Usage is implied by the purpose, but it lacks explicit context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search incidents by assignee (assignedTo), caller, priority, and/or state. All filters are optional and combined with AND. Results are newest-updated first.
| Name | Required | Description | Default |
|---|---|---|---|
| assignedTo | No | Filter by assignee user_name, e.g. "john.doe" | |
| caller | No | Filter by caller user_name | |
| priority | No | Filter by priority value: 1=Critical … 5=Planning | |
| state | No | Filter by incident state value | |
| limit | No | Max results (default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that results are ordered by newest-updated first and that filters are combined with AND. It does not mention pagination details beyond the limit parameter, but the behavior is largely transparent for a search 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 extremely concise, consisting of just two sentences. It is front-loaded with the key fields and behavior. No extraneous information is included.
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 simplicity (5 optional parameters, no output schema), the description covers the essential behavior. It explains filter combination and ordering. It could mention pagination or result fields, but overall it is complete enough for an AI agent to use 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 baseline is 3. The description adds value beyond individual parameter schemas by explaining the AND combination logic and the default ordering of results. This enhances understanding of how the parameters interact.
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: to search incidents by specific fields (assignedTo, caller, priority, state). It also specifies that all filters are optional and combined with AND. This distinguishes it from sibling tools like create_incident or update_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (when you need to search/filter incidents) and how filters combine (AND). However, it does not explicitly state when not to use it or mention alternatives, though the sibling tool list provides some differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest the most likely assignment group for a free-text issue using a documented keyword-routing rule engine. Returns {assignmentGroup, reason}.
| Name | Required | Description | Default |
|---|---|---|---|
| issue | Yes | Free-text description of the issue |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description clarifies it uses a documented keyword-routing rule engine (non-ML, deterministic) and returns a structured object {assignmentGroup, reason}. No side effects are mentioned, but none are expected. It adequately informs the agent about 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?
A single, dense sentence that immediately communicates purpose and outcome. No wasted words, and it front-loads 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?
Despite no output schema, the description explicitly states the return format. With one required parameter and a simple rule-based engine, the description provides sufficient context for an agent to use 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 coverage is 100% and already describes 'issue' as a free-text string. The description adds 'free-text' context but no additional constraints or formatting details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: suggesting the most likely assignment group for a free-text issue using a keyword-routing rule engine. It differentiates from siblings like 'assign_incident' (actual assignment) and 'classify_incident' (different scope).
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 the tool is for getting a suggestion before assigning, but lacks explicit guidance on when to use it vs alternatives (e.g., 'assign_incident'). No when-not or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a work note (internal) and/or a customer-visible comment to an incident. Provide at least one of workNote or comment.
| Name | Required | Description | Default |
|---|---|---|---|
| incidentNumber | Yes | ServiceNow incident number, e.g. "INC0012345" | |
| workNote | No | Internal work note to append | |
| comment | No | Customer-visible comment to append |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the append behavior and the requirement of at least one field, but does not mention authorization, rate limits, or whether it can update other fields. Thus it adds moderate 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 consists of two short sentences with no waste. The action is front-loaded, and the requirement is clearly stated in the second sentence.
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 tool with 100% schema coverage and no output schema, the description covers the essential aspects: what it does, what parameters are needed, and the constraint. It could hint at the response format, but that is not required by the rules.
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%, so baseline is 3. The description adds the constraint 'Provide at least one of workNote or comment', which provides additional meaning beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends work notes and/or comments to an incident, using specific verbs 'Append' and 'Provide', and distinguishes from siblings like assign_incident or close_incident by focusing solely on note/comment updates.
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 the tool is for appending notes/comments only, but does not explicitly state when not to use it or mention alternative tools. The sibling list provides context, making the usage reasonably clear.
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.
v1.0.0assign_incidentclassify_incidentclose_incidentcreate_incidentget_incidentget_knowledge_articleget_userincident_summarysearch_cmdbsearch_incidentssuggest_assignment_groupupdate_incidentScored across 12 tools
Each tool targets a distinct operation or resource: incident lifecycle (create, get, update, assign, close, search), classification, assignment group suggestion, user lookup, knowledge articles, and CMDB search. No two tools have overlapping purposes, ensuring clear distinction.
Most tools follow a consistent verb_noun pattern (e.g., assign_incident, create_incident). However, 'incident_summary' deviates by using a noun-based name, and 'search_cmdb' uses an acronym. Overall, the pattern is largely consistent with minor exceptions.
With 12 tools, the server covers the essential operations for ServiceNow incident management without being excessive. Each tool serves a clear purpose, and the count is well-scoped for the domain.
The toolset covers core incident lifecycle (create, get, assign, close, search, update notes) and additional features like classification and CMDB search. However, it lacks direct field updates (e.g., priority, state) and free-text search of incidents, which are notable gaps for full incident management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI-powered incident management and server monitoring via MCP.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
