The server provides 17 tools with basic structure and Pydantic models, but has significant gaps in schema completeness, parameter descriptions, and output documentation. Tool names follow verb_noun convention appropriately (list_incidents, get_incident, create_incident, etc.), which is good. However, most tools lack comprehensive input schema documentation, parameter constraints (enums, ranges), and explicit output schema definitions. Descriptions are present but minimal (averaging ~50-80 chars, below the 194-char baseline). No tool includes error handling guidance or recovery suggestions. Tool definitions are visible in server.py with Pydantic models for create/update operations, but many query tools lack formal schema registration. Security is partially addressed (credentials expected via env vars based on README patterns), but no per-tool permission declarations or audit trail guidance.
CRITICAL: Insufficient output schema documentation. Tools like get_incident, list_users, get_change_request return data but no structured output schema is defined or documented. LLMs cannot predict response shape for downstream tool chaining.
CRITICAL: No error handling guidance in any tool description. Tools like create_incident, update_incident, resolve_incident do not document what errors may occur or how to recover. No distinction between retryable vs fatal errors.
Add explicit JSON Schema output definitions for all tools. For list_incidents, document: {items: [{incident_id, incident_number, short_description, state, priority, created_on}], total_count, offset, limit}. Include this in tool description or a separate 'returns' section.
Convert free-text enum descriptions to formal JSON Schema enum constraints. For example, change 'state' from string to enum: ['new', 'in_progress', 'resolved', 'closed']. This prevents hallucinated values.
Add error handling guidance to mutation tools (create_incident, update_incident, resolve_incident, close_incident). Example: 'If incident not found, search_records first. If caller_id invalid, call list_users to verify. Returns 400 Bad Request if state transition invalid.'
Split ambiguous identifier parameters. Instead of 'incident_id' accepting both number and sys_id, provide 'incident_number' and 'incident_sys_id' as separate optional parameters, or add guidance: 'Pass incident number (INC0010001) if known; if only sys_id available, provide that instead.'
Enhance search_records with a discover_tables tool or documented table list. Return which tables are searchable, their required/optional fields, and valid filter operators per table type.
Add pagination metadata to list tool responses: total_count and has_more boolean. Update tool descriptions: 'Call with offset=20, limit=10 to fetch next page.'
Add dependency hints to tool descriptions. Example for add_work_note: 'If you have only the incident short_description, call search_records or list_incidents first to obtain the incident_id.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 22 points across a rubric change (v1 → v2)
44/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
44
<=2025-11-25
v2
2026-03-09
F
22
-
v1
Get a problem record from ServiceNow
get_userread onlyauth50/100
Get a user record from ServiceNow
list_change_requestsread onlyauth50/100
List change requests from ServiceNow
list_groupsread onlyauth50/100
List groups from ServiceNow
list_incidentsread onlyauthsource verified73/100
List incidents with optional filtering and search
list_problemsread onlyauth50/100
List problems from ServiceNow
list_usersread onlyauthsource verified68/100
List users from ServiceNow
resolve_incidentreversibleauth50/100
Resolve an incident with a resolution notes
search_recordsread onlyauthsource verified63/100
Search for records across any ServiceNow table using natural language
HIGH: Enum constraints missing for enumerated fields. 'state' parameter in list_incidents accepts string 'new, in_progress, resolved, closed' as free text in description rather than formal enum. Same for 'priority', 'urgency', 'impact', these invite hallucinated values.
HIGH: Bare 'incident_id' parameter accepts either 'incident number (e.g., INC0010001) or sys_id' but does not provide guidance on which format agents should prefer or how to resolve ambiguity. Parameter should use 'incident_id_or_number' naming or split into separate parameters.
HIGH: search_records tool is too generic. Accepts arbitrary 'table' name as free string without documentation of valid tables or schema variation per table. LLMs cannot reliably construct valid queries without field-level schema per table type.
MEDIUM: Pagination implemented via 'limit' and 'offset' but no total count or next_cursor returned in response. List tools cannot tell LLM whether more results exist without an additional metadata field.
MEDIUM: No dependency hints between tools. For example, add_work_note requires 'incident_id' but if the agent only has an incident 'short_description', it needs get_incident or search_records first. This is never mentioned in parameter or tool descriptions.
MEDIUM: create_incident and update_incident accept 'caller_id', 'assignment_group', 'assigned_to' as either sys_id or name, but no guidance on which is preferred or how lookup occurs. This ambiguity forces agents to reason about ID resolution.
LOW: Descriptions are terse (avg 50-80 chars vs baseline 194 chars). They state WHAT but not WHEN to use or any prerequisites. E.g., 'List incidents with optional filtering and search' does not explain when to call list_incidents vs search_records, or what fields are returned.
all tools
Declare caller_id/assignment_group/assigned_to parameter behavior explicitly. State: 'Accepts ServiceNow sys_id or human-readable name. If name provided, tool resolves to sys_id internally. If multiple matches found, returns error with matched options.'
Add per-tool permission/scope requirements in tool descriptions. Example: 'Requires read:incident and write:incident scope. Audit logged as incident_update action.'
Expand descriptions to 150-250 characters. Include WHEN to use vs similar tools, what data is returned, and any prerequisites. Example: 'List all incidents, optionally filtered by state or priority. Call this to discover incident IDs before update_incident. Returns paginated list with incident_id, short_description, state, priority, created_on. Use search_records for natural language queries.'
Add confirmation step or dry-run support to irreversible operations. For close_incident: support a 'preview' mode that returns the updated incident without persisting, or require explicit confirmation parameter.
Document rate limits and timeouts in server description. MCP tools should specify how many calls per minute are safe and expected API latency.
Create a batch variant for add_work_note and add_comment. Instead of calling 5 times to add 5 notes, accept an array: add_work_notes([{incident_id, work_note}, ...]). Reduces token count and latency for common agent workflows.